pi-mcp-adapter 2.33.0 → 2.34.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.34.0] - 2026-09-14
+
+### Highlights
+
+- Start Pi faster while keeping cached MCP tools, prompts, and commands immediately available.
+- Connect to more OAuth servers with Client ID Metadata Documents.
+- Store OAuth credentials securely in encrypted files when Windows OpenSSH or a headless session cannot use the OS credential store.
+- Load shared configuration and Agent Plugin MCP servers more reliably.
+- Use MCP Apps, private HTTPS servers, and frequently changing tool catalogs with fewer connection problems.
+
+### Added
+
+- Windows OpenSSH/network logons can explicitly select externally keyed AES-256-GCM OAuth credential files with `settings.oauthCredentialStore: "encrypted-file"`; error 1312 now points to this option, while the OS store remains the default with no automatic fallback. Thanks to [@pierreh](https://github.com/pierreh) for issue #574.
+- OAuth servers can explicitly opt into operator-hosted Client ID Metadata Documents (SEP-991) with `oauth.clientMetadataUrl`; URL-only/default configurations continue using Dynamic Client Registration. Existing DCR refresh credentials get their normal refresh attempt before migration to CIMD after invalidation. Thanks to [@dsluo](https://github.com/dsluo) for PR #571.
+- User-global or explicitly selected config can opt in to bounded ancestor `.mcp.json` and `<configDir>/mcp.json` discovery with `settings.ancestorConfigRoots`. Discovery is off by default; project files cannot enable or widen it, and the deepest matching existing directory under `$HOME` bounds farthest-first loading. Thanks to [@johnhenaot](https://github.com/johnhenaot) for PR #555.
+
+### Changed
+
+- Runtime-heavy MCP modules now load only when first needed, while cached tools, prompts, and commands remain immediately available. Thanks to [@thefakepaulgg](https://github.com/thefakepaulgg) for PR #576.
+- OAuth dependencies now use published MCP SDK releases again, restoring normal npm installs and removing the standalone native-addon dependency. Cross-process OAuth transaction serialization remains unavailable until the official SDK exposes the required support.
+
+### Fixed
+
+- Built-in Agent Plugin MCP definitions now preserve literal values through connection and cache handling, validate manifest field types, resolve contained paths through symlinks, and expand plugin placeholders once. Thanks to [@cheetahbyte](https://github.com/cheetahbyte) for #570.
+- Empty, whitespace-only, or comments-only optional MCP config layers are now treated as absent, allowing other precedence layers to load without a warning. Thanks to [@RobertoNegro](https://github.com/RobertoNegro) for PR #567.
+- macOS Keychain and Linux Secret Service now keep ordinary OAuth records in one credential item and compact existing chunks on ordinary reads; Windows Credential Manager retains chunking. Thanks to [@jploskonka](https://github.com/jploskonka) for PR #560.
+- Configured direct tools now hot-load from fresh live catalogs even when a server advertises `ttlMs: 0`, while persisted zero-TTL metadata remains non-cacheable. Thanks to [@dsluo](https://github.com/dsluo) for PR #562. (#561)
+- Switching a server between transports (HTTP to stdio command or socket) now drops an inherited `bearerTokenStore` flag alongside the other URL-bound credential fields. Thanks to [@zhulinchng](https://github.com/zhulinchng) for PR #552.
+- Per-origin `caFile` trust now routes same-origin requests through the bundled undici fetch so the custom CA dispatcher matches the fetch implementation on newer Node releases (Node 26 ships undici v8 while the dependency pins undici v6); previously every `caFile` connection failed with `UND_ERR_INVALID_ARG`. Thanks to [@zhulinchng](https://github.com/zhulinchng) for PR #550.
+- MCP Apps now load provider-declared asset, connection, and frame domains through a session-bound sandbox resource navigation with response-level CSP enforcement. Thanks to [@tekumara](https://github.com/tekumara) for #548.
+
 ## [2.33.0] - 2026-09-10
 
 ### Highlights

package/README.md

@@ -71,6 +71,10 @@ Precedence is (later entries win):
 5. `.mcp.json`
 6. `.pi/mcp.json`
 
+Ancestor discovery is off by default. To opt in, set `settings.ancestorConfigRoots` in a user-global config above, or in the explicitly selected `--mcp-config`/`configPath` file, for example `"ancestorConfigRoots": ["~/work/team"]`. Each root must be an explicit absolute path or `~/...`, resolve to an existing directory under `$HOME`, and contain the canonical cwd. If several roots match, only the nearest (deepest) is used. Project `.mcp.json` and `.pi/mcp.json` files cannot enable discovery or extend the boundary.
+
+Within the selected root, existing `.mcp.json` and `<configDir>/mcp.json` (normally `.pi/mcp.json`) files load between steps 4 and 5, from the root through parent(cwd), farthest first. Nearer directories override farther ones, Pi overrides shared config within each directory, and cwd files win over ancestors. Search never goes above the configured root or `$HOME`; the boundary limits discovery but is not a file-ownership or symlink-target sandbox. Only configure roots whose project files you trust. `/mcp setup` write targets and project-local `/mcp disable` and `/mcp enable` overrides are unchanged.
+
 `/mcp disable <server>` and `/mcp enable <server>` persist only the `disabled` field in the project-local `.pi/mcp.json`, which is the highest-precedence Pi layer. Enabling removes the project flag when lower layers are enabled, or writes `false` when needed to override a disabled lower source. This applies even when the effective server came from a shared global/project file, an imported host config, or `configPath`; the source file is never rewritten and credentials are never copied. Run `/reload` after changing the flag so registered tool surfaces are refreshed. The manual equivalent is to add `{ "disabled": true }` to a server in any normal MCP config. Supplied in-memory `createMcpAdapter({ config })` configurations are isolated and do not read or write this project override; the commands are unavailable in that mode.
 
 Servers are **lazy by default** — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections.
@@ -300,8 +304,9 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `caFile` | HTTPS HTTP servers only: local PEM CA certificate/bundle, e.g. `"caFile": "~/certs/local-ca.pem"`. Replaces (does not add to) default roots for the resolved MCP origin. Supports environment interpolation and `~`; relative paths use the process working directory. Unreadable/invalid files fail closed; hostname and certificate-expiry verification remain enabled. |
 | `auth` | `"bearer"` or `"oauth"` |
 | `oauth.grantType` | `"authorization_code"` (default) or `"client_credentials"` for non-interactive machine auth |
-| `oauth.clientId` | Pre-registered OAuth client ID. MCP 2026 prefers pre-registered clients or Client ID Metadata Documents; this adapter falls back to Dynamic Client Registration when the ID is omitted and the server supports it. |
-| `oauth.clientSecret` | OAuth client secret for confidential clients; a value beginning with `!` runs a command when OAuth authenticates, while `!!` escapes a literal leading `!` |
+| `oauth.clientId` | Pre-registered OAuth client ID. Takes precedence over `oauth.clientMetadataUrl` when both are set. |
+| `oauth.clientSecret` | OAuth client secret for confidential clients; a value beginning with `!` runs a command when OAuth authenticates, while `!!` escapes a literal leading `!`. Combining it with `oauth.clientMetadataUrl` requires an explicit `oauth.clientId`. |
+| `oauth.clientMetadataUrl` | Advanced opt-in for an operator-supplied public HTTPS Client ID Metadata Document (CIMD) URL with a non-root path. Used as the `client_id` when the authorization server advertises CIMD support; otherwise the adapter falls back to Dynamic Client Registration. The adapter does not provide or host a default document. |
 | `oauth.scope` | Requested OAuth scopes |
 | `oauth.redirectUri` | Redirect URI for browser OAuth. Dynamic clients normally omit it and use an OS-assigned localhost callback port. Local `http://` loopback URIs accept an explicit port or `{port}` for an OS-assigned port (for example, `http://127.0.0.1:{port}/callback`). Pre-registered `https://` callbacks use manual completion by pasting the full callback URL. |
 | `oauth.clientName` | Client display name advertised during Dynamic Client Registration fallback |
@@ -349,6 +354,8 @@ If an internal authorization server publishes mismatched OAuth metadata and cann
 
 If an MCP server does not publish usable protected-resource metadata, set `oauth.authServerMetadataUrl` to its HTTPS OAuth/OIDC authorization-server metadata document. The configured document is used authoritatively, while issuer validation remains enabled by default. This is trusted configuration; use it only for a metadata endpoint you control or explicitly trust.
 
+URL-only/default Pi OAuth continues to use Dynamic Client Registration; there is no project-hosted default Client ID Metadata Document. To explicitly opt into CIMD as an advanced operator setting, publish the OAuth client metadata at a stable public HTTPS URL and set `oauth.clientMetadataUrl` to that exact URL. The adapter uses it as the URL-based `client_id` only when discovered authorization-server metadata contains `client_id_metadata_document_supported: true`; servers without CIMD support continue through Dynamic Client Registration. An explicit `oauth.clientId` always wins, and `oauth.clientSecret` without that explicit ID cannot be combined with `oauth.clientMetadataUrl`.
+
 #### Stdio environment boundaries
 
 `inheritEnv: false` applies only to the actual MCP stdio server process and, for `protocolVersion: "auto"` or `"2026-07-28"`, its disposable SDK negotiation sibling. It does not change the default for other servers: omitting the field or setting it to `true` preserves the existing full host-environment inheritance. With `false`, the SDK still supplies its platform defaults and configured `env` values remain explicit overlays; the result is not a literally empty environment and is not an OS sandbox.
@@ -405,7 +412,9 @@ Public servers are ready immediately. For OAuth servers, the same action opens t
 
 If Pi is running on a remote server, `/mcp-auth <server>` shows a clickable authorization URL first. Open it in your local browser and approve access, then select **Yes** in Pi to open the callback input. The browser may fail to load the localhost callback page because localhost refers to your workstation; copy the full URL from its address bar and paste it into Pi. The authorization screen closes automatically instead when the browser can reach Pi's callback directly.
 
-The same flow is available through the proxy tool for non-interactive clients. Persistent OAuth still requires an available OS credential store; on headless Linux that usually means an unlocked Secret Service/libsecret keyring. The adapter fails closed instead of falling back to plaintext credentials when the secure store is unavailable.
+The same flow is available through the proxy tool for non-interactive clients. By default, persistent OAuth requires an available OS credential store; on headless Linux that usually means an unlocked Secret Service/libsecret keyring. The adapter fails closed instead of falling back to plaintext credentials when the secure store is unavailable.
+
+Windows OpenSSH network logons can return `ERROR_NO_SUCH_LOGON_SESSION` (1312) because Credential Manager is unavailable to that logon. For this case, explicitly set `settings.oauthCredentialStore` to `"encrypted-file"` and inject `PI_MCP_ADAPTER_OAUTH_FILE_KEY` as canonical base64 for 32 random bytes (`node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`). Encrypted entries live under the Pi agent directory's `mcp-oauth-encrypted/`; keep the key separately and reauthenticate after loss or rotation. This backend never falls back to the OS store or imports legacy plaintext; see [OAuth](OAUTH.md#token-storage) for its security model.
 
 On Linux, if credential access fails because Pi inherited a revoked session keyring, the adapter uses a best-effort recovery path through `keyctl session - node <packaged helper>` so explicit re-authentication can write fresh credentials without killing a long-lived tmux server. This path requires `keyctl` and `node` on `PATH`; missing, locked, or otherwise unavailable credential stores still fail closed.
 
@@ -475,9 +484,11 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `collapsedResultLines` | Number of result text lines to show before expansion: `1`, `2`, or `3`. Defaults to `1` in compact mode and `3` in boxed mode. |
 | `notifyOnStartupConnect` | Show successful startup connection notices (default: `true`). Set to `false` to suppress routine `MCP: N servers connected (M tools)` notices. Connection errors and authentication warnings remain visible. |
 | `hostConfigDiscovery` | Host-specific config policy: `"off"` (default), `"prompt"` (detect/report only), or `"on"` (explicitly load detected host configs as the lowest-precedence fallback) |
+| `ancestorConfigRoots` | Trusted absolute or `~/...` roots for opt-in ancestor config discovery. Only user-global or explicitly selected config may set it; the deepest root containing cwd is used. |
 | `agentPluginPaths` | Agent Plugins package directories to load MCP servers from. Relative paths resolve from the active project cwd. |
 | `approveTools` | `true` to require approval before every MCP tool call, or an array of glob patterns such as `["github_delete_*", "notion_update_*"]`. Per-server `approveTools` overrides this. |
 | `oauthDir` | Legacy OAuth `tokens.json` import directory for this MCP config. Relative paths resolve from the active project cwd. `MCP_OAUTH_DIR` still wins when set. Persistent OAuth credentials are stored in the OS credential store, not this directory. |
+| `oauthCredentialStore` | Set explicitly to `"encrypted-file"` for externally keyed AES-256-GCM storage (notably Windows OpenSSH network logons). Requires `PI_MCP_ADAPTER_OAUTH_FILE_KEY`; absent uses the OS credential store. |
 | `mcpServers.<name>.oauth.authorizationParams` | Extra authorization URL parameters for provider-specific OAuth extensions. Flow-owned parameters such as `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, `response_type`, and `resource` cannot be overridden. |
 | `directTools` | Global default for all servers (default: false). `true`, `false`, or `"search"`. Per-server overrides this. |
 | `strictDirectToolArguments` | Validate direct-tool inputs against their advertised schemas and recover one JSON string layer for object and array properties (default: false). |

package/agent-plugin-loader.ts

@@ -1,7 +1,9 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { getAgentPath } from "./agent-dir.ts";
+import { markBuiltInAgentPlugin } from "./agent-plugin-provenance.ts";
 import type { McpConfig, ServerEntry } from "./types.ts";
+import { resolveRealContainedPath } from "./utils.ts";
 
 const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
@@ -21,6 +23,8 @@ const PLUGIN_MANIFEST_FIELDS = new Set([
 const MCP_CONFIG_FIELDS = new Set(["$schema", "mcpServers"]);
 const STDIO_FIELDS = new Set(["type", "command", "args", "env", "cwd"]);
 const HTTP_FIELDS = new Set(["type", "url", "headers"]);
+const STRING_MANIFEST_FIELDS = ["version", "description", "homepage", "repository", "license"] as const;
+const AUTHOR_FIELDS = new Set(["name", "email", "url"]);
 
 interface AgentPluginManifest {
   name: string;
@@ -50,7 +54,7 @@ export function loadAgentPluginConfigs(paths: unknown, cwd = process.cwd()): Mcp
 
 export function getAgentPluginSummaries(paths: unknown, cwd = process.cwd()): AgentPluginSummary[] {
   return getPluginPaths(paths).map(path => {
-    const pluginRoot = resolvePluginPath(path, cwd);
+    const pluginRoot = resolvePluginRoot(path, cwd);
     const loaded = loadAgentPluginMcpConfig(path, cwd);
     const manifest = loaded ? readPluginManifest(pluginRoot, false) : null;
     return {
@@ -66,7 +70,7 @@ function getPluginPaths(paths: unknown): string[] {
 }
 
 function loadAgentPluginMcpConfig(path: string, cwd: string): McpConfig | null {
-  const pluginRoot = resolvePluginPath(path, cwd);
+  const pluginRoot = resolvePluginRoot(path, cwd);
   const manifest = readPluginManifest(pluginRoot, true);
   if (!manifest) return null;
 
@@ -76,10 +80,15 @@ function loadAgentPluginMcpConfig(path: string, cwd: string): McpConfig | null {
     console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: mcp.json is not a regular file`);
     return { mcpServers: {} };
   }
+  const resolvedMcpPath = resolveRealContainedPath(pluginRoot, mcpPath);
+  if (!resolvedMcpPath) {
+    console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: mcp.json must stay inside the plugin directory`);
+    return { mcpServers: {} };
+  }
 
   let raw: unknown;
   try {
-    raw = JSON.parse(readFileSync(mcpPath, "utf8"));
+    raw = JSON.parse(readFileSync(resolvedMcpPath, "utf8"));
   } catch (error) {
     console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: failed to parse mcp.json`, error);
     return { mcpServers: {} };
@@ -98,10 +107,15 @@ function readPluginManifest(pluginRoot: string, report: boolean): AgentPluginMan
     if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: plugin.json is not a regular file`);
     return null;
   }
+  const resolvedManifestPath = resolveRealContainedPath(pluginRoot, manifestPath);
+  if (!resolvedManifestPath) {
+    if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: plugin.json must stay inside the plugin directory`);
+    return null;
+  }
 
   let raw: unknown;
   try {
-    raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+    raw = JSON.parse(readFileSync(resolvedManifestPath, "utf8"));
   } catch (error) {
     if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: failed to parse plugin.json`, error);
     return null;
@@ -125,6 +139,20 @@ function readPluginManifest(pluginRoot: string, report: boolean): AgentPluginMan
     if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: plugin.json name is invalid`);
     return null;
   }
+  for (const field of STRING_MANIFEST_FIELDS) {
+    if (manifest[field] !== undefined && typeof manifest[field] !== "string") {
+      if (report) console.warn(`Agent Plugin ${manifest.name} is invalid: plugin.json ${field} must be a string`);
+      return null;
+    }
+  }
+  if (manifest.keywords !== undefined && (!Array.isArray(manifest.keywords) || manifest.keywords.some(value => typeof value !== "string"))) {
+    if (report) console.warn(`Agent Plugin ${manifest.name} is invalid: plugin.json keywords must be an array of strings`);
+    return null;
+  }
+  if (manifest.author !== undefined && !isValidManifestAuthor(manifest.author)) {
+    if (report) console.warn(`Agent Plugin ${manifest.name} is invalid: plugin.json author is invalid`);
+    return null;
+  }
   if (manifest.extensions !== undefined && (!manifest.extensions || typeof manifest.extensions !== "object" || Array.isArray(manifest.extensions))) {
     if (report) console.warn(`Agent Plugin ${manifest.name} ignores non-object plugin.json extensions`);
   }
@@ -205,14 +233,14 @@ function translateStdioServer(
   const env = translateEnv(raw.env, manifest, serverName);
   if (env === null) return null;
 
-  const command = raw.command.startsWith("./") ? resolveContainedPath(pluginRoot, raw.command, pluginRoot) : raw.command;
-  if (command === null) return skipServer(manifest, serverName, "command must stay inside the plugin directory");
+  const command = raw.command.startsWith("./") ? resolveRealContainedPath(pluginRoot, resolve(pluginRoot, raw.command)) : raw.command;
+  if (command === null) return skipServer(manifest, serverName, "command must resolve to an accessible path inside the plugin directory");
 
   const pluginDataDir = getAgentPath("agent-plugin-data", manifest.name);
   const cwd = resolvePluginCwd(raw.cwd, pluginRoot, pluginDataDir);
-  if (cwd === null) return skipServer(manifest, serverName, "cwd must be plugin-relative, PLUGIN_ROOT-rooted, or PLUGIN_DATA-rooted");
+  if (cwd === null) return skipServer(manifest, serverName, "cwd must resolve from an allowed root and stay contained");
 
-  return {
+  return markBuiltInAgentPlugin({
     command,
     args: args.map(value => expandPluginPlaceholders(value, pluginRoot, pluginDataDir)),
     env: {
@@ -223,7 +251,7 @@ function translateStdioServer(
     cwd,
     pluginDataDir,
     literalEnv: true,
-  };
+  }, ["args", "env", "cwd"]);
 }
 
 function translateHttpServer(
@@ -240,11 +268,11 @@ function translateHttpServer(
   const headers = translateHeaders(raw.headers, manifest, serverName);
   if (headers === null) return null;
 
-  return {
+  return markBuiltInAgentPlugin({
     url: raw.url,
     httpTransport: type,
     ...(headers ? { headers } : {}),
-  };
+  }, headers ? ["headers"] : []);
 }
 
 function formatAgentPluginServerName(pluginName: string, serverName: string): string {
@@ -273,7 +301,7 @@ function translateEnv(value: unknown, manifest: AgentPluginManifest, serverName:
     console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: env must be an object of strings`);
     return null;
   }
-  const env: Record<string, string> = {};
+  const entries: Array<[string, string]> = [];
   for (const [key, entry] of Object.entries(value)) {
     if (key === "PLUGIN_ROOT" || key === "PLUGIN_DATA") {
       console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: env must not define ${key}`);
@@ -283,9 +311,9 @@ function translateEnv(value: unknown, manifest: AgentPluginManifest, serverName:
       console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: env values must be strings`);
       return null;
     }
-    env[key] = entry;
+    entries.push([key, entry]);
   }
-  return env;
+  return Object.fromEntries(entries);
 }
 
 function translateHeaders(value: unknown, manifest: AgentPluginManifest, serverName: string): Record<string, string> | undefined | null {
@@ -294,7 +322,7 @@ function translateHeaders(value: unknown, manifest: AgentPluginManifest, serverN
     console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: headers must be an object of strings`);
     return null;
   }
-  const headers: Record<string, string> = {};
+  const entries: Array<[string, string]> = [];
   const seen = new Set<string>();
   for (const [key, entry] of Object.entries(value)) {
     if (typeof entry !== "string") {
@@ -307,8 +335,9 @@ function translateHeaders(value: unknown, manifest: AgentPluginManifest, serverN
       return null;
     }
     seen.add(normalized);
-    headers[key] = entry;
+    entries.push([key, entry]);
   }
+  const headers = Object.fromEntries(entries);
   try {
     new Headers(headers);
   } catch {
@@ -324,6 +353,20 @@ function resolvePluginPath(path: string, cwd: string): string {
   return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
 }
 
+function resolvePluginRoot(path: string, cwd: string): string {
+  const resolved = resolvePluginPath(path, cwd);
+  try {
+    return realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function isValidManifestAuthor(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.entries(value).every(([key, entry]) => AUTHOR_FIELDS.has(key) && typeof entry === "string");
+}
+
 function isBareCommand(command: string): boolean {
   return !command.includes("/") && !command.includes("\\") && !command.includes("${PLUGIN_ROOT}") && !command.includes("${PLUGIN_DATA}");
 }
@@ -331,27 +374,23 @@ function isBareCommand(command: string): boolean {
 function resolvePluginCwd(value: unknown, pluginRoot: string, pluginDataDir: string): string | null {
   if (value === undefined) return pluginRoot;
   if (typeof value !== "string") return null;
-  if (value.startsWith("./")) return resolveContainedPath(pluginRoot, value, pluginRoot);
-  if (value === "${PLUGIN_ROOT}" || value.startsWith("${PLUGIN_ROOT}/")) {
-    return resolveContainedPath(pluginRoot, value.replace("${PLUGIN_ROOT}", "."), pluginRoot);
+  const expanded = expandPluginPlaceholders(value, pluginRoot, pluginDataDir);
+  if (value.startsWith("./") || value === "${PLUGIN_ROOT}" || value.startsWith("${PLUGIN_ROOT}/")) {
+    return resolveRealContainedPath(pluginRoot, resolve(pluginRoot, expanded));
   }
   if (value === "${PLUGIN_DATA}" || value.startsWith("${PLUGIN_DATA}/")) {
-    return resolveContainedPath(pluginDataDir, value.replace("${PLUGIN_DATA}", "."), pluginDataDir);
+    return resolvePluginDataCwd(pluginDataDir, expanded);
   }
   return null;
 }
 
-function resolveContainedPath(root: string, value: string, containmentRoot: string): string | null {
-  const resolved = resolve(root, value);
-  const rel = relative(containmentRoot, resolved);
-  if (rel === "" || (!rel.startsWith("..") && !rel.startsWith(sep) && !isAbsolute(rel))) return resolved;
-  return null;
+function resolvePluginDataCwd(pluginDataDir: string, expanded: string): string | null {
+  if (existsSync(pluginDataDir) && !resolveRealContainedPath(dirname(pluginDataDir), pluginDataDir)) return null;
+  return resolveRealContainedPath(pluginDataDir, resolve(pluginDataDir, expanded), true);
 }
 
 function expandPluginPlaceholders(value: string, pluginRoot: string, pluginDataDir: string): string {
-  return value
-    .replaceAll("${PLUGIN_ROOT}", pluginRoot)
-    .replaceAll("${PLUGIN_DATA}", pluginDataDir);
+  return value.replace(/\$\{PLUGIN_(ROOT|DATA)\}/g, (_, name: string) => name === "ROOT" ? pluginRoot : pluginDataDir);
 }
 
 function isValidAgentPluginUrl(value: string): boolean {

package/agent-plugin-provenance.ts

@@ -0,0 +1,36 @@
+import type { ServerEntry } from "./types.ts";
+
+const LITERAL_PLUGIN_FIELDS = ["args", "env", "cwd", "headers"] as const;
+type LiteralPluginField = typeof LITERAL_PLUGIN_FIELDS[number];
+const BUILT_IN_AGENT_PLUGIN = Symbol("built-in-agent-plugin");
+type BuiltInAgentPluginEntry = ServerEntry & { [BUILT_IN_AGENT_PLUGIN]?: ReadonlySet<LiteralPluginField> };
+
+/** @internal */
+export function markBuiltInAgentPlugin(definition: ServerEntry, fields: LiteralPluginField[]): ServerEntry {
+  (definition as BuiltInAgentPluginEntry)[BUILT_IN_AGENT_PLUGIN] = new Set(fields);
+  return definition;
+}
+
+/** @internal */
+export function isBuiltInAgentPlugin(definition: ServerEntry, field: LiteralPluginField): boolean {
+  return (definition as BuiltInAgentPluginEntry)[BUILT_IN_AGENT_PLUGIN]?.has(field) === true;
+}
+
+/** @internal */
+export function cloneBuiltInAgentPluginEntry(source: ServerEntry): ServerEntry | undefined {
+  const fields = LITERAL_PLUGIN_FIELDS.filter(field => Object.hasOwn(source, field) && isBuiltInAgentPlugin(source, field));
+  if (fields.length === 0) return undefined;
+  return markBuiltInAgentPlugin(structuredClone(source), fields);
+}
+
+/** @internal */
+export function mergeBuiltInAgentPluginEntries(base: ServerEntry, next: ServerEntry): ServerEntry {
+  const merged = { ...base, ...next };
+  delete (merged as BuiltInAgentPluginEntry)[BUILT_IN_AGENT_PLUGIN];
+  const fields = LITERAL_PLUGIN_FIELDS.filter(field => {
+    const owner = Object.hasOwn(next, field) ? next : base;
+    return Object.hasOwn(owner, field) && isBuiltInAgentPlugin(owner, field);
+  });
+  if (fields.length > 0) markBuiltInAgentPlugin(merged, fields);
+  return merged;
+}

package/commands.ts

@@ -311,9 +311,9 @@ export async function authenticateServer(
     }
 
     ui.setStatus("mcp-auth", `Authenticating ${serverName}...`);
-    const authStorageOptions = getAuthStorageOptions(config.settings?.oauthDir, cwd);
+    const authStorageOptions = getAuthStorageOptions(config.settings?.oauthDir, cwd, config.settings?.oauthCredentialStore);
     const status = await authenticate(serverName, serverUrl, definition, {
-      ...(authStorageOptions.baseDir ? { authStorageOptions } : {}),
+      ...(Object.keys(authStorageOptions).length > 0 ? { authStorageOptions } : {}),
       onAuthorizationUrl: () => {},
       onAuthorizationInput: async (authorizationUrl, inputSignal) => {
         if (inputSignal.aborted) return undefined;
@@ -365,12 +365,23 @@ export async function logoutServer(
   const signal = state.owner?.signal;
   try {
     await state.manager.close(serverName);
+  } catch (error) {
+    if (isAbortError(error, signal)) throw error;
+    const message = error instanceof Error ? error.message : String(error);
+    if (ui) {
+      ui.notify(`Failed to close OAuth server "${serverName}"; credentials were not cleared: ${sanitizeTerminalText(message)}`, "error");
+    }
+    return { ok: false, message };
+  }
+
+  state.owner?.throwIfInactive();
+  try {
     await removeAuth(serverName, { authStorageOptions: state.authStorageOptions, signal, runtime: state.oauthRuntime });
   } catch (error) {
     if (isAbortError(error, signal)) throw error;
     const message = error instanceof Error ? error.message : String(error);
     if (ui) {
-      ui.notify(`Failed to disconnect or clear OAuth credentials for "${serverName}": ${sanitizeTerminalText(message)}`, "error");
+      ui.notify(`Failed to clear OAuth credentials for "${serverName}": ${sanitizeTerminalText(message)}`, "error");
     }
     return { ok: false, message };
   }
@@ -460,7 +471,7 @@ function buildSharedConfigNoticeLines(configOverridePath: string | undefined, cw
   const discovery = getMcpStandardConfigSummary(configOverridePath, cwd);
   const onboardingState = loadOnboardingState();
   const sharedSources = discovery.sources.filter((source) =>
-    (source.id === "shared-project" || source.id === "shared-global") && source.serverCount > 0,
+    (source.id === "shared-project" || source.id === "shared-project-ancestor" || source.id === "shared-global") && source.serverCount > 0,
   );
   if (sharedSources.length === 0 || onboardingState.sharedConfigHintShown) {
     return { lines: [], fingerprint: null };

package/config.ts

@@ -1,10 +1,12 @@
 // config.ts - Config loading with import support
-import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parse as parseToml } from "smol-toml";
+import stripJsonComments from "strip-json-comments";
 import { getAgentPath, getConfigDirName } from "./agent-dir.ts";
 import { getAgentPluginSummaries, loadAgentPluginConfigs, type AgentPluginSummary } from "./agent-plugin-loader.ts";
+import { cloneBuiltInAgentPluginEntry, isBuiltInAgentPlugin, mergeBuiltInAgentPluginEntries } from "./agent-plugin-provenance.ts";
 import { loadClaudePluginBundles } from "./claude-plugin-loader.ts";
 import { loadPackageMcpConfigs } from "./package-mcp-loader.ts";
 import { formatServerNamespace, isServerDisabled, type ClaudePluginConfig, type HostConfigDiscovery, type McpConfig, type ServerEntry, type McpSettings, type ImportKind, type ServerProvenance } from "./types.ts";
@@ -93,7 +95,7 @@ const IMPORT_PATHS: Record<ImportKind, string[]> = {
 };
 
 interface ConfigSourceSpec {
-  id: "shared-global" | "agents-global" | "agents-nested-global" | "pi-global" | "shared-project" | "pi-project";
+  id: "shared-global" | "agents-global" | "agents-nested-global" | "pi-global" | "shared-project-ancestor" | "pi-project-ancestor" | "shared-project" | "pi-project";
   label: string;
   readPath: string;
   writePath: string;
@@ -312,7 +314,12 @@ export function getMcpDiscoverySummary(
 }
 
 export function cloneMcpConfig(config: McpConfig): McpConfig {
-  return structuredClone(config);
+  const cloned = structuredClone(config);
+  for (const [name, source] of Object.entries(config.mcpServers)) {
+    const builtInClone = cloneBuiltInAgentPluginEntry(source);
+    if (builtInClone) cloned.mcpServers[name] = builtInClone;
+  }
+  return cloned;
 }
 
 export function loadMcpConfig(overridePath?: string, cwd = process.cwd()): McpConfig {
@@ -502,6 +509,43 @@ function getConfigSources(overridePath?: string, cwd = process.cwd()): ConfigSou
     scope: "global",
   });
 
+  // Compare file identities so symlink aliases cannot reload a global source
+  // at ancestor precedence. Keep original paths for display and writes.
+  const reservedPaths = new Set([
+    ...sources.map((source) => getConfigPathIdentity(source.readPath)),
+    getConfigPathIdentity(projectPath),
+    getConfigPathIdentity(projectPiPath),
+  ]);
+  // Only user-global files (including an explicit override) may opt in to
+  // ancestor discovery. Project files cannot extend this trust boundary.
+  const ancestorSources = new Map<string, ConfigSourceSpec>();
+  const descriptors = [
+    { id: "shared-project-ancestor", label: "ancestor standard MCP", path: getProjectConfigPath, shared: true },
+    { id: "pi-project-ancestor", label: "ancestor Pi override", path: getProjectPiConfigPath, shared: false },
+  ] as const;
+  const ancestorRoot = getConfiguredAncestorRoot(sources, cwd);
+  if (ancestorRoot) {
+    for (const dir of getAncestorProjectDirs(cwd, ancestorRoot)) {
+      for (const descriptor of descriptors) {
+        const path = descriptor.path(dir);
+        const identity = getConfigPathIdentity(path);
+        if (reservedPaths.has(identity) || !existsSync(path)) continue;
+        // Reinsert aliases at their nearest precedence position.
+        ancestorSources.delete(identity);
+        ancestorSources.set(identity, {
+          id: descriptor.id,
+          label: descriptor.label,
+          readPath: path,
+          writePath: path,
+          kind: "project",
+          shared: descriptor.shared,
+          scope: "project",
+        });
+      }
+    }
+  }
+  sources.push(...ancestorSources.values());
+
   if (projectPath !== userPath) {
     sources.push({
       id: "shared-project",
@@ -529,6 +573,68 @@ function getConfigSources(overridePath?: string, cwd = process.cwd()): ConfigSou
   return sources;
 }
 
+function getConfigPathIdentity(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    // Missing or inaccessible paths still participate in lexical deduplication.
+    return resolve(path);
+  }
+}
+
+function isWithin(base: string, target: string): boolean {
+  const path = relative(base, target);
+  return path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path);
+}
+
+function getConfiguredAncestorRoot(globalSources: ConfigSourceSpec[], cwd: string): string | undefined {
+  let configured: unknown;
+  for (const source of globalSources) {
+    const roots = readValidatedConfig(source.readPath, `MCP config from ${source.readPath}`)?.settings?.ancestorConfigRoots;
+    if (roots !== undefined) configured = roots;
+  }
+  if (configured === undefined || (Array.isArray(configured) && configured.length === 0)) return undefined;
+  if (!Array.isArray(configured)) {
+    console.warn("Invalid settings.ancestorConfigRoots: expected an array of paths");
+    return undefined;
+  }
+
+  const home = getConfigPathIdentity(resolve(homedir()));
+  const canonicalCwd = getConfigPathIdentity(resolve(cwd));
+  const valid: string[] = [];
+  for (const entry of configured) {
+    const expanded = typeof entry === "string" && entry.startsWith("~/")
+      ? join(homedir(), entry.slice(2))
+      : entry;
+    if (typeof expanded !== "string" || !isAbsolute(expanded)) {
+      console.warn(`Invalid settings.ancestorConfigRoots entry ${JSON.stringify(entry)}: expected an absolute path or ~/...`);
+      continue;
+    }
+    try {
+      const root = realpathSync(expanded);
+      if (!statSync(root).isDirectory() || !isWithin(home, root) || !isWithin(root, canonicalCwd)) throw new Error();
+      valid.push(root);
+    } catch {
+      console.warn(`Invalid settings.ancestorConfigRoots entry ${JSON.stringify(entry)}: expected an existing directory under HOME containing cwd`);
+    }
+  }
+  return valid.sort((left, right) => right.length - left.length)[0];
+}
+
+function getAncestorProjectDirs(cwd: string, root: string): string[] {
+  const start = getConfigPathIdentity(resolve(cwd));
+  const dirs: string[] = [];
+  let current = dirname(start);
+  while (isWithin(root, current)) {
+    dirs.unshift(current);
+    if (current === root) break;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return dirs;
+}
+
 function isExclusiveConfigMode(): boolean {
   return process.env.PI_MCP_CONFIG_MODE?.trim().toLowerCase() === "exclusive";
 }
@@ -574,7 +680,7 @@ function mergeServerMaps(
       baseEntry = { ...existing };
       for (const field of [
         "url", "headers", "requestHeadersCommand", "caFile", "auth", "bearerToken",
-        "bearerTokenEnv", "oauth", "httpTransport", "socket",
+        "bearerTokenEnv", "bearerTokenStore", "oauth", "httpTransport", "socket",
       ] as const) {
         delete baseEntry[field];
       }
@@ -590,7 +696,7 @@ function mergeServerMaps(
       for (const field of [
         "command", "args", "env", "cwd", "pluginDataDir", "literalEnv", "inheritEnv", "url",
         "headers", "requestHeadersCommand", "caFile", "auth", "bearerToken", "bearerTokenEnv",
-        "oauth", "httpTransport",
+        "bearerTokenStore", "oauth", "httpTransport",
       ] as const) {
         delete baseEntry[field];
       }
@@ -604,7 +710,11 @@ function mergeServerMaps(
         delete baseEntry.oauth;
       }
     }
-    merged[name] = { ...baseEntry, ...definition };
+    if (existing && Object.hasOwn(definition, "env") && isBuiltInAgentPlugin(existing, "env") && !Object.hasOwn(definition, "literalEnv")) {
+      if (baseEntry === existing) baseEntry = { ...existing };
+      delete baseEntry.literalEnv;
+    }
+    merged[name] = mergeBuiltInAgentPluginEntries(baseEntry, definition);
   }
   return merged;
 }
@@ -719,7 +829,9 @@ function readValidatedConfig(path: string, label: string): McpConfig | null {
   if (!existsSync(path)) return null;
 
   try {
-    return validateConfig(parseJsonWithComments(readFileSync(path, "utf-8")));
+    const text = readFileSync(path, "utf-8");
+    if (stripJsonComments(text, { trailingCommas: true }).trim() === "") return null;
+    return validateConfig(parseJsonWithComments(text));
   } catch (error) {
     console.warn(`Failed to load ${label}:`, error);
     return null;
@@ -905,6 +1017,7 @@ function extractServers(config: unknown, kind: ImportKind): Record<string, Serve
           mapped.oauth = {
             ...(typeof oauth.clientId === "string" ? { clientId: oauth.clientId } : {}),
             ...(typeof oauth.clientSecret === "string" ? { clientSecret: oauth.clientSecret } : {}),
+            ...(typeof oauth.clientMetadataUrl === "string" ? { clientMetadataUrl: oauth.clientMetadataUrl } : {}),
             ...(typeof oauth.scope === "string" ? { scope: oauth.scope } : {}),
             ...(typeof oauth.authServerMetadataUrl === "string" ? { authServerMetadataUrl: oauth.authServerMetadataUrl } : {}),
             ...(typeof oauth.skipIssuerMetadataValidation === "boolean"