@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/pi-lens/skills/pi-lens-write-ast-grep-rule/reference.md

@@ -0,0 +1,129 @@
+# pi-lens ast-grep Rule Reference
+
+Deep-dive companion to `SKILL.md`. Read this when you're debugging a rule
+that isn't matching (or over-matching) the way you expect: ReDoS-safe regex
+authoring, string-escape quirks in node text, `has`/`inside` `stopBy`
+defaults and when to override them, boolean-parameter matching across two
+grammars, and precision-over-recall heuristics for denylist-shaped rules.
+
+## Hard-won gotchas (NAPI runner specifics — verified)
+
+```
+⚠ `has`/`inside` default to DIRECT child/parent — add `stopBy: end` for a recursive search.
+   This cuts BOTH ways, so think about where the target node actually lives:
+   - Target is a grandchild+ → you MUST add `stopBy: end` or the `has` never matches.
+     `switch-without-default` = `switch_statement` not has `switch_default`: the default
+     lives under `switch_body`, so without `stopBy: end` it matches nothing and every
+     switch (even ones WITH a default) is flagged. Same for `nested-ternary` catching a
+     parenthesized `a ? (b ? c : d) : e`.
+   - Target is the direct child → leave it at `neighbor` (default). Adding `stopBy: end`
+     OVER-reports: `throw_statement` has `string` + `stopBy: end` flags `throw new
+     Error("x")` (the string is nested), and `expression_statement` has `new_expression`
+     + `stopBy: end` flags `fn(new Error())` as a discarded error. Keep these direct.
+   napi's `has` never matches the node itself, so a self-referential `kind: X` has
+   `kind: X` (with `stopBy: end`) correctly flags only genuinely-nested X.
+
+✅ Prefer `regex` on the matched node's OWN text over `has` when you only need to
+   inspect the node — avoids recursive-descendant false positives:
+     kind: export_statement
+     regex: '^export\s+(let|var)\b'      # precise; no has-recursion FP
+   (NAPI evaluates `regex` with JS RegExp on node.text() — keep it LINEAR so the
+   detector can't itself ReDoS.)
+
+⚠ String-literal regexes match SOURCE text, not the runtime string value.
+   Inspect the exact node text before writing constraints:
+     ast-grep run --kind string --lang ts sample.ts --json=compact
+   Example: source `"\\|"` is node text `"\\\\|"` in JSON; to match a
+   source-level escaped backslash (`\\`) followed by a non-backslash, the rule
+   regex needs FOUR regex backslashes, preferably in a YAML block scalar:
+     regex: >-
+       ^["'`]\\\\[^\\A-Za-z0-9$]
+   This is how `incomplete-string-escaping` catches both `"\\|"` and
+   `'\\"'`. Avoid shell here-doc probes for this class — shell/JSON escaping
+   can silently eat a backslash and make the rule look broken.
+
+⚠ `-js` twins: remember there are TWO execution surfaces.
+   <!-- verified: clients/dispatch/runners/ast-grep-napi.ts:205-216,450-455, c170d94b -->
+   - ast-grep CLI/LSP language-gates by `language:`. A `language: TypeScript`
+     rule is not enough for standalone `.js` coverage, so shipped user-facing
+     TS/JS rules that should fire under the ast-grep LSP usually need a `-js`
+     twin with `language: JavaScript` plus its own fixture.
+   - the in-process NAPI fallback (`ast-grep-napi.ts` — pi-lens source checkout
+     only, not present in the installed package) already DEDUPES by grammar
+     (#657): `ruleLanguageForFile` (`ast-grep-napi.ts:205-216`) maps each file
+     extension to its actual grammar, and the matcher (`:450-455`) skips any
+     `language:`-tagged rule whose tag doesn't match that grammar. A TS rule
+     and its JS twin no longer double-fire on the same file in fallback mode.
+   - **`-js` twins are needed only when the rule body itself is
+     grammar-divergent** (different node kinds/fields between the TS and JS
+     grammars). A grammar-agnostic body doesn't need a twin for fallback
+     coverage — the dedup above already scopes it correctly; ship a twin only
+     when standalone `.js` coverage through the ast-grep CLI/LSP baseline is
+     required (see the first bullet).
+   - **Grammar-divergent bodies** still need separate variants regardless:
+     e.g. `no-flag-argument` uses `required_parameter` in TS and
+     `assignment_pattern` in JS.
+
+✅ Node-kind facts (tree-sitter-typescript grammar — NOT the TS compiler / Roslyn):
+   - let / const  → `lexical_declaration`     (var is NOT here)
+   - var          → `variable_declaration`
+   - a regex literal's pattern text  → `regex_pattern`
+   - x[i] index access  → `subscript_expression`   (NOT element_access_expression)
+   - obj.prop access    → `member_expression`      (NOT property_access_expression)
+   - !x / -x / typeof x → `unary_expression`
+   - a ? b : c          → `ternary_expression`
+
+❌ Wrong-grammar kind names = silent dead rule. `element_access_expression`,
+   `property_access_expression`, `binary_operator`, etc. are TS-compiler/Roslyn names, not
+   tree-sitter's. napi REJECTS the whole rule ("invalid kind matcher") so it never runs.
+   Verify a kind exists before shipping:
+     node -e 'import("@ast-grep/napi").then(s=>{const r=s.ts.parse("x[i]").root();
+       const f=(n,k)=>{let c=n.kind()===k?1:0;for(const x of n.children())c+=f(x,k);return c};
+       console.log(f(r,"subscript_expression"))})'   # >0 means the kind is real
+
+✅ Test through the REAL runner from the pi-lens source checkout's repo root — it loads the actual shipped
+   rules from rules/ast-grep-rules/rules. Assert on diagnostic `rule` ids:
+     const res = await runner.run(ctx);  // ctx.filePath = temp .ts, cwd = repo  (pi-lens source checkout only — not present in the installed package)
+   For pattern/kind/regex-only rules (CLI-identical semantics) `ast-grep scan` is fine.
+
+✅ Before shipping any text/regex detector, FP-scan the codebase:
+     ast-grep scan -r <rule>.yml clients tools
+   Real safe variants bite (e.g. ReDoS: (ba+)+ is safe — a mandatory prefix makes
+   the partition unique; flag only a single quantified atom inside the group).
+```
+
+## Matching things a pattern can't express (#305)
+
+```
+❌ A parameter default is NOT a `$X = false` pattern. `pattern: $FLAG = false` parses as
+   an `assignment_expression` (statement context) and never matches a function parameter.
+   Match the PARAM NODE + its child literal instead, capturing the name for reuse:
+     # TS grammar
+     - kind: required_parameter
+       all:
+         - has: { field: pattern, pattern: $FLAG }
+         - has: { any: [ { kind: "true" }, { kind: "false" } ] }
+     # JS grammar (assignment_pattern, with fields left/right)
+     - kind: assignment_pattern
+       all:
+         - has: { field: left, pattern: $FLAG }
+         - has: { field: right, any: [ { kind: "true" }, { kind: "false" } ] }
+
+✅ Metavar consistency works ACROSS sibling clauses of an `all` — a metavar bound in one
+   `has` must match the SAME text everywhere it reappears. Use it to CORRELATE nodes, which
+   is what makes a structural rule precise:
+     all:
+       - has: { stopBy: end, kind: required_parameter, has: { field: pattern, pattern: $FLAG } }
+       - has: { stopBy: end, any: [ { pattern: "if ($FLAG) $$$" }, { pattern: "if (!$FLAG) $$$" } ] }
+   This fires ONLY when the function branches on the SAME param it declared boolean — a
+   boolean default that's never branched on, or a branch on a different var, won't match.
+
+❌ Two `has:` keys in one mapping silently OVERWRITE (YAML: last key wins). For multiple
+   descendant constraints use `all:` with a LIST of `has` entries, never repeated `has:`.
+
+✅ Prefer a high-precision structural guard over an unbounded denylist. Message-chain
+   (Demeter) floods on fluent/promise/builder chains; rather than denylist every fluent
+   method name, REQUIRE the chain's first calls to be accessors (`get*`/`is*`/`has*`) via
+   `constraints` regex — promise/fluent/builder methods aren't accessor-named, so they're
+   excluded by construction. Precision over recall.
+```

package/node_modules/pi-lens/skills/pi-lens-write-tree-sitter-rule/SKILL.md

@@ -6,7 +6,7 @@ description: Use when writing a new pi-lens tree-sitter query rule YAML file —
 # Writing a pi-lens tree-sitter Rule
 
 Drop path: `rules/tree-sitter-queries/<language>/<id>.yml`  
-Language dir is **lowercase**: `typescript` `javascript` `tsx` `python` `go` `rust` `java` `csharp` `kotlin` `ruby` `cpp` `c` `css`
+Language dir is **lowercase**: `typescript` `javascript` `tsx` `python` `go` `rust` `java` `csharp` `kotlin` `php` `ruby` `cpp` `c` `css`
 
 Project rules merge with built-ins (both run). To disable a language's built-ins: rename dir to `<lang>-disabled/`.
 
@@ -115,6 +115,8 @@ predicates:
    treeSitterRunner.run() via makeRealRunnerCtx (tests/support/real-runner-ctx.ts) —
    runQueryOnFile bypasses dispatch (skip_test_files, tiers, delta, rule cache).
    Template: tests/clients/dispatch/runners/tree-sitter-skip-test-files.test.ts.
+   (These test paths exist only in a pi-lens source checkout — the installed
+   npm package ships no tests/ directory.)
 
 ✅ JS files also run typescript/ rules (shared grammar) — one rule in
    rules/tree-sitter-queries/typescript/ covers BOTH .ts and .js. No -js copy needed.

package/node_modules/pi-mcp-adapter/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.26.0] - 2026-08-14
+
+### Added
+- Added per-server `requestHeadersCommand` support for deriving fail-closed HTTP headers from the exact outbound request on every Streamable HTTP or SSE call. Thanks @kgreen18 for PR #353.
+- Added `settings.warnOnLargeDirectTools` to suppress the advisory for 75 or more resolved direct tools. Thanks @Roshvan for issue #358.
+
+### Changed
+- Refined request-header command result handling types without changing runtime behavior.
+
+### Fixed
+- Matched adapter-owned config and state paths to the host agent directory when Pi is rebranded, including its environment override and config directory. Thanks @mindplay-dk for issue #356.
+- Avoided O(tools²) cross-server tool-name collision scans at startup by skipping collision candidates when selectors are absent and sharing one indexed candidate set when `includeTools` or `excludeTools` is configured. Thanks @mjlbach for PR #357 and @cataldoc for issue #354.
+
+## [2.25.0] - 2026-08-13
+
+### Added
+- Added `settings.notifyOnStartupConnect` to suppress successful MCP startup connection notices. Thanks @pierre-mgmt for issue #341.
+- Added compact self-rendered MCP proxy and direct-tool result rows by default, with `settings.toolResultRendering: "boxed"` for the legacy boxed row and `settings.collapsedResultLines` for 1-3 collapsed result lines. Thanks @pierre-mgmt for issue #349.
+
+### Changed
+- Removed unused TypeScript declarations found by stricter compiler checks.
+
+### Fixed
+- Kept `mcpScript` tool-call replies flowing when Pi runs as a Bun-compiled binary by starting worker execution without module-level top-level await. Thanks @AndreiKopylov for issue #340 and @thesobercoder for the verified fix.
+- Fixed direct-tool server prefixes to preserve provider-valid underscores and hyphens, including `codebase-memory-mcp`, while retaining safe escaping, collision handling, and exact proxy routing. Thanks @mightymatth for issue #342 and @JasonLandbridge for issue #343.
+
+## [2.24.0] - 2026-08-13
+
+### Added
+- Added per-server `searchKeywords` so `mcp({ search })` and `mcpScript` `tools.search` understand user-defined synonyms and aliases for tools. Keywords are keyed by tool name or glob and boost ranked and regex search only. They never appear in tool schemas, describe output, or the metadata cache. Thanks @Serisium for PR #336.
+
+### Fixed
+- Interpolated environment placeholders in stdio server arguments. Thanks @vjik for issue #333.
+- Kept remote `/mcp-auth` authorization links reachable before the callback input opens. Thanks @trevorleibert-mixpanel for PR #331.
+- Cached OAuth credentials in memory and refreshed them after OAuth-backed 401 responses. Thanks @daniel-sampliner for PR #335.
+- Sanitized MCP server-name prefixes for provider-safe tool names while preserving server resolution. Thanks @triple-dex for issue #334.
+- Validated persisted npx resolver cache entries before reuse, including malformed and prototype-sensitive persisted keys.
+
 ## [2.23.0] - 2026-08-11
 
 ### Added

package/node_modules/pi-mcp-adapter/README.md

@@ -207,6 +207,7 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `cwd` | Working directory; supports `${VAR}`, `$env:VAR`, and `~` expansion |
 | `url` | HTTP endpoint (StreamableHTTP with SSE fallback); supports raw `${VAR}` and `$env:VAR` interpolation, and missing URL variables fail before any request is sent |
 | `headers` | HTTP headers; supports `${VAR}` and `$env:VAR` interpolation. A value beginning with `!` runs a command when the HTTP server connects or OAuth authenticates; use `!!` for a literal leading `!`. |
+| `requestHeadersCommand` | Trusted executable run for every HTTP request. It receives a versioned JSON envelope containing `method`, `url`, and the exact `bodyBase64` on stdin, and must return a JSON object of headers on stdout. `command`, `args`, and `env` support environment interpolation. Use for caller-bound request signatures; failures stop the request. |
 | `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. |
@@ -227,6 +228,7 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `toolPrefix` | Override global `settings.toolPrefix` for this server (`"server"`, `"short"`, `"none"`, or `"mcp"`) |
 | `includeTools` | `string[]` of tool names or glob patterns to expose (matches original names like `get_screenshot`, generated resource names like `read_figjam`, and prefixed names like `figma_get_screenshot`) |
 | `excludeTools` | `string[]` of tool names or glob patterns to hide (applied after `includeTools`) |
+| `searchKeywords` | `{ "tool-or-glob": ["keyword", ...] }` — extra keywords that boost `mcp({ search })` ranking for matching tools; never shown to the model |
 | `debug` | Show server stderr (default: false) |
 | `trace` | Enable metadata-only JSONL protocol tracing for this server; payloads, prompts, tool arguments/results, authorization data, and URLs are never persisted |
 | `disabled` | Keep the server visible in config and status, but prevent connections, authentication, tools, and resource calls (only literal `true` disables it) |
@@ -265,7 +267,7 @@ The adapter owns only its client socket and closes that connection when the Pi r
 
 ### Remote/headless OAuth
 
-If Pi is running on a remote server, `/mcp-auth <server>` prints the authorization URL and opens a callback input. Open the URL in your local browser. After approval, 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 input closes automatically instead when the browser can reach Pi's callback directly.
+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.
 
@@ -306,6 +308,10 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
     "requestTimeoutMs": 30000,
     "showStatusIcon": true,
     "mcpFooterStatus": "full",
+    "toolResultRendering": "compact",
+    "collapsedResultLines": 1,
+    "notifyOnStartupConnect": true,
+    "warnOnLargeDirectTools": true,
     "hostConfigDiscovery": "off",
     "approveTools": ["github_delete_*", "notion_update_*"],
     "oauthDir": ".pi/mcp-oauth",
@@ -327,12 +333,16 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `requestTimeoutMs` | Global request timeout in milliseconds for live MCP calls (if omitted or `<= 0`, the MCP SDK default timeout is used) |
 | `showStatusIcon` | Show the plug icon in MCP status and connection text (default: `true`). Set to `false` for plain `MCP: ...` text. |
 | `mcpFooterStatus` | MCP footer verbosity: `"full"` (default), `"compact"` for `MCP connected/enabled`, or `"off"` to clear the persistent footer status. `/mcp status` remains available. |
+| `toolResultRendering` | MCP tool result row style: `"compact"` (default) uses self-rendered rows, or `"boxed"` restores the legacy Pi boxed tool row. |
+| `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) |
 | `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. |
 | `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). Per-server overrides this. |
+| `warnOnLargeDirectTools` | Show the advisory when 75 or more direct tools resolve (default: `true`). Set to `false` to suppress only this advisory. |
 | `freezeDirectTools` | Keep direct-tool registration stable after the initial sync so automatic reconnects and list-change notifications do not rebuild the system prompt. Use `mcp({ connect: "server" })` or `/mcp reconnect <server>` to refresh deliberately. Default: false. |
 | `scriptMode` | Register the MCP-only `mcpScript` plain-JavaScript tool (default: true). Set to `false` to hide it. |
 | `disableProxyTool` | Hide the `mcp` proxy tool once configured direct tools are fully available from cache. |
@@ -537,7 +547,7 @@ To hide specific tools while still using `directTools: true`, add `excludeTools`
 
 `includeTools` and `excludeTools` filter direct tools, proxy search/list/describe, and the `/mcp` panel view.
 
-Each direct tool costs ~150-300 tokens in the system prompt (name + description + schema). Good for targeted sets of 5-20 tools. For servers with 75+ tools, stick with the proxy or pick specific tools with a `string[]`. If 75+ direct tools resolve, the adapter prints a warning but still registers the tools you configured.
+Each direct tool costs ~150-300 tokens in the system prompt (name + description + schema). Good for targeted sets of 5-20 tools. For servers with 75+ tools, stick with the proxy or pick specific tools with a `string[]`. If 75+ direct tools resolve, the adapter prints an advisory but still registers the tools you configured. Set `settings.warnOnLargeDirectTools` to `false` to suppress this advisory.
 
 Direct tools register from the metadata cache in the Pi agent dir (`~/.pi/agent/mcp-cache.json` by default, or `$PI_CODING_AGENT_DIR/mcp-cache.json` when set), so no server connections are needed at startup. On the first session after adding `directTools` to a new server, the cache won't exist yet — tools fall back to proxy-only while the cache populates, then the extension hot-loads the refreshed direct tools into the current session. Servers that advertise MCP list-change notifications refresh the current session when their tool or resource list changes. On Pi versions that expose `pi.unregisterTool()`, stale direct tools are removed from the registry during refresh; older Pi versions still deactivate them from the active tool set. To force a refresh: `/mcp reconnect <server>`.
 
@@ -648,12 +658,35 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only
 
 `mcp({ connect: "server-name" })` refreshes an already connected server, so new tools, resources, prompts, and instructions can load without restarting Pi.
 
-MCP proxy and direct-tool results render compactly by default: long text shows the first three terminal-wrapped lines plus a `Ctrl+O to expand` hint, while the full result remains available when expanded and is still returned unchanged to the model.
+MCP proxy and direct-tool results use compact self-rendered rows by default. Collapsed success output shows the call title and the first result line, with a `Ctrl+O to expand` hint when more text is hidden. The full result remains available when expanded and is still returned unchanged to the model. Set `settings.toolResultRendering` to `"boxed"` to restore the legacy boxed Pi row, or set `settings.collapsedResultLines` to `2` or `3` when you want more collapsed text.
 
-Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are ranked by weighted matches across name, server, and description, then returned one page at a time (`limit` defaults to 12). Use `details.nextOffset` for the next page. Regex search is still available with `regex: true`, but regex results are paginated without ranking.
+Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are ranked by weighted matches across name, server, description, and any configured `searchKeywords`, then returned one page at a time (`limit` defaults to 12). Use `details.nextOffset` for the next page. Regex search is still available with `regex: true`, but regex results are paginated without ranking.
 
 Tool names are fuzzy-matched on hyphens and underscores — `context7_resolve_library_id` finds `context7_resolve-library-id`. When `describe` or `tool` cannot resolve a name, the result includes top suggestions so the agent can correct a typo or missing prefix in the same turn.
 
+### Search keywords
+
+Search uses literal matching so a tool whose name and description use different vocabulary than the query won't be found. Per-server `searchKeywords` adds extra vocabulary for matching tools:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "searchKeywords": {
+        "search_code": ["grep"],
+        "*": ["gh"]
+      }
+    }
+  }
+}
+```
+
+With this config, `mcp({ search: "grep" })` finds `github_search_code` even though neither its name nor description contains that word. Similarly, `mcp({ search: "gh" })` finds all tools provided by the github server.
+
+Keys match a tool's original name, prefixed name, or a glob (`*` applies to every tool on the server) and all matching entries combine. Keywords are weighted like description text, with an extra boost when the query exactly matches a configured phrase. They affect ranked and regex search only (including `tools.search` in `mcpScript`): they never appear in tool schemas, `describe` output, direct-tool registration, or the metadata cache, and search with keywords works offline from cached metadata.
+
 When `includeSchemas` is enabled, search and describe render common JSON Schema parameters as compact TypeScript shapes like `{ query: string; limit?: number; }`, with the older schema formatter retained as a fallback for unsupported schemas.
 
 For HTTP servers, failed connects run a one-request shape probe that can turn opaque transport errors into setup hints such as `endpoint returned HTML (200) — this URL does not appear to speak MCP`. Healthy connections are not probed.
@@ -699,4 +732,5 @@ Advertised tool `outputSchema` values support JSON Schema draft-07 and 2020-12.
 
 - Cross-session server sharing not yet implemented (each Pi session runs its own server processes)
 - Compact MCP result rendering summarizes text, but inline images are still controlled by Pi's image display settings and may render below the compact text summary.
+- Pi still owns one separator row before self-rendered tool output, so compact mode reduces adapter rendering height but cannot promise true zero-gap rows.
 - MCP sampling support is text-only; context inclusion, tools, stop sequences, audio, and image content are rejected with explicit errors.

package/node_modules/pi-mcp-adapter/agent-dir.ts

@@ -2,10 +2,18 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
+export function getConfigDirName(): string {
+  const configDir = readPiConfig()?.configDir;
+  return typeof configDir === "string" && configDir.trim() ? configDir.trim() : ".pi";
+}
+
 export function getAgentDir(): string {
-  const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+  const piConfig = readPiConfig();
+  const name = piConfig?.name;
+  const appName = typeof name === "string" && name.trim() ? name.trim() : "pi";
+  const configured = process.env[`${appName.toUpperCase()}_CODING_AGENT_DIR`]?.trim();
   if (!configured) {
-    return join(homedir(), ".pi", "agent");
+    return join(homedir(), getConfigDirName(), "agent");
   }
   if (configured === "~") {
     return homedir();
@@ -31,12 +39,12 @@ export function getAgentPath(...segments: string[]): string {
  *
  * Falls back to "pi", which is what pi's own APP_NAME resolves to.
  */
-function readPiConfig(): { name?: unknown; clientUri?: unknown } | undefined {
+function readPiConfig(): { name?: unknown; configDir?: unknown; clientUri?: unknown } | undefined {
   const dir = process.env.PI_PACKAGE_DIR?.trim()
   if (!dir) return undefined
   try {
     const manifest = JSON.parse(readFileSync(join(resolve(dir), "package.json"), "utf8")) as {
-      piConfig?: { name?: unknown; clientUri?: unknown }
+      piConfig?: { name?: unknown; configDir?: unknown; clientUri?: unknown }
     }
     return manifest.piConfig
   } catch {

package/node_modules/pi-mcp-adapter/agent-plugin-loader.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { getAgentPath } from "./agent-dir.ts";
 import type { McpConfig, ServerEntry } from "./types.ts";

package/node_modules/pi-mcp-adapter/cli.js

@@ -14,15 +14,36 @@ function expandHome(input) {
   return path.resolve(input);
 }
 
-const AGENT_DIR = process.env.PI_CODING_AGENT_DIR?.trim()
-  ? expandHome(process.env.PI_CODING_AGENT_DIR.trim())
-  : path.join(HOME, ".pi", "agent");
+function readPiConfig() {
+  const dir = process.env.PI_PACKAGE_DIR?.trim();
+  if (!dir) return undefined;
+  try {
+    return JSON.parse(fs.readFileSync(path.join(path.resolve(dir), "package.json"), "utf8")).piConfig;
+  } catch {
+    return undefined;
+  }
+}
+
+function getConfigDirName() {
+  const configDir = readPiConfig()?.configDir;
+  return typeof configDir === "string" && configDir.trim() ? configDir.trim() : ".pi";
+}
+
+function getAgentDir() {
+  const piConfig = readPiConfig();
+  const appName = typeof piConfig?.name === "string" && piConfig.name.trim() ? piConfig.name.trim() : "pi";
+  const configured = process.env[`${appName.toUpperCase()}_CODING_AGENT_DIR`]?.trim();
+  if (configured) return expandHome(configured);
+  return path.join(HOME, getConfigDirName(), "agent");
+}
+
+const AGENT_DIR = getAgentDir();
 const PI_CONFIG_PATH = path.join(AGENT_DIR, "mcp.json");
 const GENERIC_GLOBAL_CONFIG_PATH = path.join(HOME, ".config", "mcp", "mcp.json");
 const AGENTS_GLOBAL_CONFIG_PATH = path.join(HOME, ".agents", "mcp.json");
 const AGENTS_NESTED_GLOBAL_CONFIG_PATH = path.join(HOME, ".agents", "mcp", "mcp.json");
 const PROJECT_CONFIG_PATH = path.resolve(process.cwd(), ".mcp.json");
-const PROJECT_PI_CONFIG_PATH = path.resolve(process.cwd(), ".pi", "mcp.json");
+const PROJECT_PI_CONFIG_PATH = path.resolve(process.cwd(), getConfigDirName(), "mcp.json");
 
 const IMPORT_PATHS = {
   cursor: [path.join(HOME, ".cursor", "mcp.json")],

package/node_modules/pi-mcp-adapter/commands.ts

@@ -12,7 +12,6 @@ import {
   previewSharedServerEntry,
   previewStarterProjectConfig,
   writeDirectToolsConfig,
-  writeProjectServerDisabledOverride,
   writeSharedServerEntry,
   writeStarterProjectConfig,
 } from "./config.ts";
@@ -170,7 +169,7 @@ export async function reconnectServer(
     }
 
     const prefix = state.config.settings?.toolPrefix ?? "server";
-    const { metadata, failedTools } = buildToolMetadata(connection.tools, connection.resources, definition, name, prefix);
+    const { metadata, failedTools } = buildToolMetadata(connection.tools, connection.resources, definition, name, prefix, state.config.mcpServers, state.toolMetadata);
     state.toolMetadata.set(name, metadata);
     if (!connection.promptDiscoveryFailed) {
       state.promptMetadata?.set(name, reconstructPromptMetadata(name, connection.prompts ?? [], prefix, definition));
@@ -283,11 +282,20 @@ export async function authenticateServer(
           "info"
         );
       },
-      onAuthorizationInput: (_authorizationUrl, inputSignal) => ui.input(
-        `Complete ${serverName} OAuth`,
-        "Paste the full callback URL, or wait for automatic completion",
-        { signal: inputSignal },
-      ),
+      onAuthorizationInput: async (authorizationUrl, inputSignal) => {
+        const readyToPaste = await ui.confirm(
+          `Authorize ${serverName}`,
+          `Open this link in your browser:\n${terminalHyperlink(authorizationUrl, authorizationUrl)}\n\n` +
+          "After approving access, select Yes to paste the callback URL.",
+          { signal: inputSignal },
+        );
+        if (!readyToPaste || inputSignal.aborted) return undefined;
+        return ui.input(
+          `Complete ${serverName} OAuth`,
+          "Paste the full callback URL",
+          { signal: inputSignal },
+        );
+      },
       ...(signal ? { signal } : {}),
       ...(runtime ? { runtime } : {}),
     });

package/node_modules/pi-mcp-adapter/config.ts

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import stripJsonComments from "strip-json-comments";
-import { getAgentPath } from "./agent-dir.ts";
+import { getAgentPath, getConfigDirName } from "./agent-dir.ts";
 import { getAgentPluginSummaries, loadAgentPluginConfigs, type AgentPluginSummary } from "./agent-plugin-loader.ts";
 import { isServerDisabled, type HostConfigDiscovery, type McpConfig, type ServerEntry, type McpSettings, type ImportKind, type ServerProvenance } from "./types.ts";
 import { toStringRecord } from "./utils.ts";
@@ -15,7 +15,7 @@ const AGENTS_GLOBAL_CONFIG_PATHS = [
   join(homedir(), ".agents", "mcp", "mcp.json"),
 ] as const;
 const PROJECT_CONFIG_NAME = ".mcp.json";
-const PROJECT_PI_CONFIG_NAME = ".pi/mcp.json";
+const PROJECT_PI_CONFIG_NAME = "mcp.json";
 const REPOPROMPT_BINARY_CANDIDATES = [
   join(homedir(), "RepoPrompt", "repoprompt_cli"),
   "/Applications/Repo Prompt.app/Contents/MacOS/repoprompt-mcp",
@@ -177,7 +177,7 @@ export function getProjectConfigPath(cwd = process.cwd()): string {
 }
 
 export function getProjectPiConfigPath(cwd = process.cwd()): string {
-  return resolve(cwd, PROJECT_PI_CONFIG_NAME);
+  return resolve(cwd, getConfigDirName(), PROJECT_PI_CONFIG_NAME);
 }
 
 export function getConfigDiscoveryPaths(overridePath?: string, cwd = process.cwd()): ConfigDiscoveryPath[] {
@@ -471,7 +471,7 @@ function mergeConfigs(base: McpConfig, next: McpConfig): McpConfig {
 // different url, these MUST NOT be inherited from the lower-precedence entry —
 // otherwise the original endpoint's credentials would be shipped to the new
 // url. See the SECURITY note in mergeServerMaps.
-const URL_BOUND_AUTH_FIELDS = ["headers", "bearerToken", "bearerTokenEnv"] as const;
+const URL_BOUND_AUTH_FIELDS = ["headers", "bearerToken", "bearerTokenEnv", "requestHeadersCommand"] as const;
 
 function mergeServerMaps(
   base: Record<string, ServerEntry>,

package/node_modules/pi-mcp-adapter/direct-tools.ts

@@ -11,7 +11,8 @@ import { formatSchema } from "./tool-metadata.ts";
 import { resolveMcpResultContent, transformMcpContent, transformMcpResourceContents } from "./tool-registrar.ts";
 import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
 import { maybeStartUiSession, summarizeUiSessionResult, type UiSessionRuntime } from "./ui-session.ts";
-import { formatToolName, isServerDisabled, isToolAllowed, resolveToolPrefix } from "./types.ts";
+import { createToolSelectorCandidateIndex, formatToolName, getToolNameCandidates, isServerDisabled, isToolAllowed, resolveToolPrefix } from "./types.ts";
+import { isUiToolVisibleToModel } from "./ui-tool-visibility.ts";
 import { resourceNameToToolName } from "./resource-tools.ts";
 import { authenticate, supportsOAuth } from "./mcp-auth-flow.ts";
 import { formatAuthRequiredMessage, resolveServerUrl, truncateAtWord } from "./utils.ts";
@@ -149,10 +150,33 @@ export function resolveDirectTools(
     if (!toolFilter) continue;
 
     const effectivePrefix = resolveToolPrefix(definition, prefix);
+    const hasToolFilters =
+      (Array.isArray(definition.includeTools) && definition.includeTools.length > 0) ||
+      (Array.isArray(definition.excludeTools) && definition.excludeTools.length > 0);
+    const selectorCandidateIndex = hasToolFilters ? (() => {
+      const candidates = new Set<string>();
+      for (const [otherServerName, otherDefinition] of Object.entries(config.mcpServers)) {
+        const otherCache = cache.servers[otherServerName];
+        if (!otherCache || !isServerCacheValid(otherCache, otherDefinition) || isServerDisabled(otherDefinition)) continue;
+        const otherPrefix = resolveToolPrefix(otherDefinition, prefix);
+        for (const otherTool of otherCache.tools ?? []) {
+          if (!isUiToolVisibleToModel(otherTool.uiVisibility)) continue;
+          for (const candidate of getToolNameCandidates(otherTool.name, otherServerName, otherPrefix, false)) candidates.add(candidate);
+        }
+        if (otherDefinition.exposeResources !== false) {
+          for (const resource of otherCache.resources ?? []) {
+            const baseName = `read_${resourceNameToToolName(resource.name)}`;
+            for (const candidate of getToolNameCandidates(baseName, otherServerName, otherPrefix, false)) candidates.add(candidate);
+          }
+        }
+      }
+      return createToolSelectorCandidateIndex(candidates);
+    })() : undefined;
 
     for (const tool of serverCache.tools ?? []) {
+      if (!isUiToolVisibleToModel(tool.uiVisibility)) continue;
       if (toolFilter !== true && !toolFilter.includes(tool.name)) continue;
-      if (!isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools)) continue;
+      if (!isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex)) continue;
       const prefixedName = formatToolName(tool.name, serverName, effectivePrefix);
       if (BUILTIN_NAMES.has(prefixedName)) {
         console.warn(`MCP: skipping direct tool "${prefixedName}" (collides with builtin)`);
@@ -178,7 +202,7 @@ export function resolveDirectTools(
       for (const resource of serverCache.resources ?? []) {
         const baseName = `read_${resourceNameToToolName(resource.name)}`;
         if (toolFilter !== true && !toolFilter.includes(baseName)) continue;
-        if (!isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools)) continue;
+        if (!isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex)) continue;
         const prefixedName = formatToolName(baseName, serverName, effectivePrefix);
         if (BUILTIN_NAMES.has(prefixedName)) {
           console.warn(`MCP: skipping direct resource tool "${prefixedName}" (collides with builtin)`);
@@ -200,7 +224,7 @@ export function resolveDirectTools(
     }
   }
 
-  if (specs.length >= DIRECT_TOOLS_ADVISORY_THRESHOLD) {
+  if (config.settings?.warnOnLargeDirectTools !== false && specs.length >= DIRECT_TOOLS_ADVISORY_THRESHOLD) {
     console.warn(`MCP: ${specs.length} direct tools resolved. Each direct tool adds prompt context; README guidance recommends targeted sets of 5-20 tools and using the proxy or an explicit string[] when 75+ direct tools would be registered.`);
   }
 
@@ -230,15 +254,39 @@ export function buildProxyDescription(
   for (const serverName of Object.keys(config.mcpServers)) {
     const definition = config.mcpServers[serverName];
     if (!definition || isServerDisabled(definition)) continue;
-    const entry = cache?.servers?.[serverName];
+    const cachedEntry = cache?.servers?.[serverName];
+    const entry = cachedEntry && isServerCacheValid(cachedEntry, definition) ? cachedEntry : undefined;
     const effectivePrefix = resolveToolPrefix(definition, prefix);
+    const hasToolFilters =
+      (Array.isArray(definition.includeTools) && definition.includeTools.length > 0) ||
+      (Array.isArray(definition.excludeTools) && definition.excludeTools.length > 0);
+    const selectorCandidateIndex = hasToolFilters && cache ? (() => {
+      const candidates = new Set<string>();
+      for (const [otherServerName, otherDefinition] of Object.entries(config.mcpServers)) {
+        const otherEntry = cache.servers[otherServerName];
+        if (!otherEntry || !isServerCacheValid(otherEntry, otherDefinition) || isServerDisabled(otherDefinition)) continue;
+        const otherPrefix = resolveToolPrefix(otherDefinition, prefix);
+        for (const otherTool of otherEntry.tools ?? []) {
+          if (!isUiToolVisibleToModel(otherTool.uiVisibility)) continue;
+          for (const candidate of getToolNameCandidates(otherTool.name, otherServerName, otherPrefix, false)) candidates.add(candidate);
+        }
+        if (otherDefinition.exposeResources !== false) {
+          for (const resource of otherEntry.resources ?? []) {
+            const baseName = `read_${resourceNameToToolName(resource.name)}`;
+            for (const candidate of getToolNameCandidates(baseName, otherServerName, otherPrefix, false)) candidates.add(candidate);
+          }
+        }
+      }
+      return createToolSelectorCandidateIndex(candidates);
+    })() : undefined;
     const toolCount = (entry?.tools ?? []).filter(
-      (tool) => isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools),
+      (tool) => isUiToolVisibleToModel(tool.uiVisibility)
+        && isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex),
     ).length;
     const resourceCount = definition?.exposeResources !== false
       ? (entry?.resources ?? []).filter((resource) => {
           const baseName = `read_${resourceNameToToolName(resource.name)}`;
-          return isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools);
+          return isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex);
         }).length
       : 0;
     const totalItems = toolCount + resourceCount;
@@ -264,7 +312,9 @@ export function buildProxyDescription(
   const instructionSummaries: string[] = [];
   for (const serverName of Object.keys(config.mcpServers)) {
     if (isServerDisabled(config.mcpServers[serverName])) continue;
-    const instructions = cache?.servers?.[serverName]?.instructions;
+    const definition = config.mcpServers[serverName];
+    const entry = definition && cache?.servers?.[serverName];
+    const instructions = entry && definition && isServerCacheValid(entry, definition) ? entry.instructions : undefined;
     if (!instructions) continue;
     const snippet = truncateAtWord(instructions.replace(/\s+/g, " ").trim(), INSTRUCTIONS_SNIPPET_LENGTH);
     instructionSummaries.push(`  ${serverName}: ${snippet}`);

package/node_modules/pi-mcp-adapter/host-html-template.ts

@@ -459,11 +459,3 @@ function escapeHtml(value: string): string {
     .replace(/"/g, """)
     .replace(/'/g, "'");
 }
-
-function escapeHtmlAttribute(value: string): string {
-  return value
-    .replace(/&/g, "&")
-    .replace(/"/g, """)
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
-}