@herbertgao/pi-extensions 2026.8.5 → 2026.8.6

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

@@ -67,7 +67,7 @@ constraints:                  # metavariable regex constraints work
 
 ⚠ **`has`/`inside` default to the immediate child/parent (`stopBy: neighbor`).** For a
 recursive descendant/ancestor search add `stopBy: end`. This is the #1 migration
-gotcha — see the `has` note below.
+gotcha — see the `has` note in `reference.md`.
 
 ## YAML quoting — REQUIRED (js-yaml will reject the rule otherwise)
 
@@ -100,120 +100,14 @@ The parser is a real YAML parser, so unquoted special chars throw and the rule i
 ✅ Docs: docs/custom-rules.md
 ```
 
-## Hard-won gotchas (NAPI runner specifics — verified)
+## Reference doc — read before writing a NAPI-runner-specific or hard-to-express rule
 
-```
-⚠ `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.
-   - 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`) parses the target file's
-     own grammar and currently runs both TS and JS rules on every jsts file. A
-     grammar-agnostic twin can therefore duplicate in fallback mode.
-   - **Decide explicitly:** if the rule must cover `.js` through the ast-grep
-     CLI/LSP baseline, ship the twin and test both. If a rule is NAPI-only or
-     fallback duplication is unacceptable, fix runner dedup/normalization before
-     relying on a single TypeScript rule for JS coverage.
-   - **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 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
-   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.
+`reference.md` (same directory) covers: ReDoS-safe regex authoring, node-text
+string-escape quirks, `has`/`inside` `stopBy` defaults (and when to override
+them), the `-js` twin dedup behavior (#657), boolean-parameter matching
+across the TS/JS grammars, and precision-over-recall heuristics for
+denylist-shaped rules. Read it when a rule isn't matching (or over-matching)
+the way you expect, or before shipping a `regex`/`has`-heavy rule.
 
 ## Validating a candidate rule against the REAL engine (not the warm MCP cache)
 

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,19 @@ 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

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. |
@@ -310,6 +311,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
     "toolResultRendering": "compact",
     "collapsedResultLines": 1,
     "notifyOnStartupConnect": true,
+    "warnOnLargeDirectTools": true,
     "hostConfigDiscovery": "off",
     "approveTools": ["github_delete_*", "notion_update_*"],
     "oauthDir": ".pi/mcp-oauth",
@@ -340,6 +342,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `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. |
@@ -544,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>`.
 

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/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/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,7 @@ 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, getToolNameCandidates, 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";
@@ -150,7 +150,10 @@ export function resolveDirectTools(
     if (!toolFilter) continue;
 
     const effectivePrefix = resolveToolPrefix(definition, prefix);
-    const getOtherCurrentCandidates = (toolName: string): Set<string> => {
+    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];
@@ -167,14 +170,13 @@ export function resolveDirectTools(
           }
         }
       }
-      for (const candidate of getToolNameCandidates(toolName, serverName, effectivePrefix, false)) candidates.delete(candidate);
-      return candidates;
-    };
+      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, getOtherCurrentCandidates(tool.name))) 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)`);
@@ -200,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, getOtherCurrentCandidates(baseName))) 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)`);
@@ -222,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.`);
   }
 
@@ -255,8 +257,10 @@ export function buildProxyDescription(
     const cachedEntry = cache?.servers?.[serverName];
     const entry = cachedEntry && isServerCacheValid(cachedEntry, definition) ? cachedEntry : undefined;
     const effectivePrefix = resolveToolPrefix(definition, prefix);
-    const getOtherCurrentCandidates = (toolName: string): Set<string> | undefined => {
-      if (!cache) return undefined;
+    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];
@@ -273,17 +277,16 @@ export function buildProxyDescription(
           }
         }
       }
-      for (const candidate of getToolNameCandidates(toolName, serverName, effectivePrefix, false)) candidates.delete(candidate);
-      return candidates;
-    };
+      return createToolSelectorCandidateIndex(candidates);
+    })() : undefined;
     const toolCount = (entry?.tools ?? []).filter(
       (tool) => isUiToolVisibleToModel(tool.uiVisibility)
-        && isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, getOtherCurrentCandidates(tool.name)),
+        && 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, getOtherCurrentCandidates(baseName));
+          return isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex);
         }).length
       : 0;
     const totalItems = toolCount + resourceCount;

package/node_modules/pi-mcp-adapter/mcp-setup-panel.ts

@@ -1,6 +1,7 @@
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { createPanelKeys, type PanelKeybindings, type PanelKeys } from "./panel-keys.ts";
 import type { ImportKind } from "./types.ts";
+import { getConfigDirName } from "./agent-dir.ts";
 import { KNOWN_SERVER_PRESETS, type ConfigWritePreview, type KnownServerPreset, type McpDiscoverySummary } from "./config.ts";
 import type { McpOnboardingState } from "./onboarding-state.ts";
 
@@ -556,7 +557,7 @@ export class McpSetupPanel {
           "3. ~/.agents/mcp/mcp.json",
           "4. <Pi agent dir>/mcp.json",
           "5. .mcp.json",
-          "6. .pi/mcp.json",
+          `6. ${getConfigDirName()}/mcp.json`,
           `Host discovery: ${this.discovery.hostConfigDiscovery}. Conflicts reported: ${this.discovery.conflicts.length}.`,
           ...this.discovery.conflicts.slice(0, 8).map((conflict) =>
             `${conflict.serverName}: ${conflict.sources.map((source) => source.path).join(" -> ")} (winner: ${conflict.winner.path})`,

package/node_modules/pi-mcp-adapter/metadata-cache.ts

@@ -19,11 +19,12 @@ import type {
   ToolMetadata,
   PromptMetadata,
 } from "./types.ts";
-import { formatPromptCommandName, formatToolName, getToolNameCandidates, isServerDisabled, isToolAllowed, resolveToolPrefix, type ToolPrefix } from "./types.ts";
+import { createToolSelectorCandidateIndex, formatPromptCommandName, formatToolName, getToolNameCandidates, isServerDisabled, isToolAllowed, resolveToolPrefix, type ToolPrefix } from "./types.ts";
 import { resourceNameToToolName } from "./resource-tools.ts";
 import {
   extractToolUiStreamMode,
   interpolateEnvRecord,
+  interpolateEnvVars,
   resolveBearerToken,
   resolveConfigPath,
   resolveServerUrl,
@@ -90,6 +91,14 @@ export function computeServerHash(definition: ServerEntry): string {
     cwd: resolveConfigPath(definition.cwd),
     url: resolveServerUrl(definition),
     headers: interpolateEnvRecord(definition.headers),
+    requestHeadersCommand: definition.requestHeadersCommand
+      ? {
+          command: interpolateEnvVars(definition.requestHeadersCommand.command),
+          args: definition.requestHeadersCommand.args?.map(interpolateEnvVars),
+          env: interpolateEnvRecord(definition.requestHeadersCommand.env),
+          timeoutMs: definition.requestHeadersCommand.timeoutMs,
+        }
+      : undefined,
     auth: definition.auth,
     protocolVersion: definition.protocolVersion,
     bearerToken: resolveBearerToken(definition),
@@ -184,8 +193,10 @@ export function reconstructToolMetadata(
   const metadata: ToolMetadata[] = [];
   const seenNames = new Set<string>();
   const effectivePrefix = resolveToolPrefix(definition, prefix);
-  const getOtherCurrentCandidates = (toolName: string): Set<string> | undefined => {
-    if (!configuredServers || !cache) return undefined;
+  const hasToolFilters =
+    (Array.isArray(definition.includeTools) && definition.includeTools.length > 0) ||
+    (Array.isArray(definition.excludeTools) && definition.excludeTools.length > 0);
+  const selectorCandidateIndex = hasToolFilters && configuredServers && cache ? (() => {
     const candidates = new Set<string>();
     for (const [otherServerName, otherDefinition] of Object.entries(configuredServers)) {
       const otherEntry = cache.servers[otherServerName];
@@ -202,16 +213,15 @@ export function reconstructToolMetadata(
         }
       }
     }
-    for (const candidate of getToolNameCandidates(toolName, serverName, effectivePrefix, false)) candidates.delete(candidate);
-    return candidates;
-  };
+    return createToolSelectorCandidateIndex(candidates);
+  })() : undefined;
 
   for (const tool of entry.tools ?? []) {
     if (!tool?.name) continue;
     if (!isUiToolVisibleToModel(tool.uiVisibility)) {
       continue;
     }
-    if (!isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, getOtherCurrentCandidates(tool.name))) {
+    if (!isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex)) {
       continue;
     }
 
@@ -236,7 +246,7 @@ export function reconstructToolMetadata(
     for (const resource of entry.resources ?? []) {
       if (!resource?.name || !resource?.uri) continue;
       const baseName = `read_${resourceNameToToolName(resource.name)}`;
-      if (!isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, getOtherCurrentCandidates(baseName))) {
+      if (!isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex)) {
         continue;
       }