pi-code 1.0.61 → 1.0.62

package/extensions/internal/command-file.ts

@@ -18,6 +18,8 @@ import * as path from 'node:path'
 
 import { parseFrontmatter } from '@earendil-works/pi-coding-agent'
 
+import { CLAUDE_TOOL_MAP } from './claude-tool-names.js'
+
 /** The pi file tools a Claude path rule can govern. */
 export type PathRuleTool = 'read' | 'edit' | 'write'
 
@@ -27,6 +29,12 @@ export interface ParsedCommand {
   allowedTools?: string[]
   /** Claude `Bash(...)` specifiers, present only when every bash grant is scoped. */
   bashRules?: string[]
+  /** Claude `WebFetch(domain:...)` specifiers, on the same unscoped-wins rule. */
+  domainRules?: string[]
+  /** Claude `Agent(...)`/`Task(...)` agent names, on the same unscoped-wins rule. */
+  agentRules?: string[]
+  /** Claude `Skill(...)` name patterns, on the same unscoped-wins rule. */
+  skillRules?: string[]
   /** Claude path rules per pi file tool, from Read(...)/Edit(...)/Write(...) grants. */
   pathRules?: Partial<Record<PathRuleTool, string[]>>
   /** Names from the `arguments:` frontmatter list, mapped to positions in order. */
@@ -58,34 +66,6 @@ export interface DiscoveredCommand {
   plugin?: { root: string; dataDir: string; userConfig?: Record<string, string> }
 }
 
-/** Claude tool names are PascalCase and do not all exist in pi: `Glob` is pi's
- * `find`. Lowercasing alone left `glob` in the list, and since pi has no tool by
- * that name the grant was silently dropped when the list was intersected with the
- * active tools. Shared with the subagent's own frontmatter parsing. */
-const CLAUDE_TOOL_MAP: Record<string, string> = {
-  read: 'read',
-  write: 'write',
-  edit: 'edit',
-  bash: 'bash',
-  grep: 'grep',
-  glob: 'find',
-  ls: 'ls',
-  // Claude's names for the tools this package registers itself. Without these a
-  // perfectly ordinary `allowed-tools: WebFetch, WebSearch` matched no pi tool and
-  // the intersection left the turn with nothing.
-  webfetch: 'web_fetch',
-  websearch: 'web_search',
-  todowrite: 'todo',
-  todoread: 'todo',
-  task: 'subagent',
-  askuserquestion: 'question',
-  exitplanmode: 'plan_mode_complete',
-  // Claude's name for the tool this package registers so the model can run user slash
-  // commands; without it `allowed-tools: SlashCommand` matched nothing and the grant
-  // could neither keep nor drop the tool.
-  slashcommand: 'slash_command',
-}
-
 /**
  * The pi tool name for one grant entry, scope and all: `Bash(git add:*)` is `bash`.
  * Keeping the scope in the name matched nothing when the list was intersected with
@@ -135,6 +115,14 @@ export interface ToolGrants {
   /** Claude `Bash(...)` specifiers, present only when every bash grant is scoped:
    * an unscoped `Bash` entry is the wider grant and wins over its scoped siblings. */
   bashRules?: string[]
+  /** Claude `WebFetch(domain:host)` specifiers, same unscoped-wins rule as bash.
+   * Dropping them granted unrestricted web_fetch to a command that asked for one host. */
+  domainRules?: string[]
+  /** Claude `Agent(AgentName)` names from `Agent(...)` or the legacy `Task(...)`,
+   * same unscoped-wins rule. Dropping them granted the whole subagent tool. */
+  agentRules?: string[]
+  /** Claude `Skill(name)` / `Skill(name *)` specifiers, same unscoped-wins rule. */
+  skillRules?: string[]
   /** Claude path rules per pi file tool, absent for a tool with an unscoped grant.
    * Edit scopes govern writes too, as Claude documents; Write scopes are honored
    * rather than Claude's accept-and-warn-then-ignore, which would fail open here. */
@@ -150,18 +138,32 @@ const PATH_RULE_TOOLS: Record<string, Array<PathRuleTool>> = {
   write: ['write'],
 }
 
+/** pi tools whose Claude specifier is a scalar argument scope rather than a path
+ * rule: `Bash(cmd)`, `WebFetch(domain:host)` and `Agent(AgentName)`. One list, so a
+ * tool cannot be granted a scope here and quietly miss the unscoped-wins rule. */
+const ARG_RULE_TOOLS = ['bash', 'web_fetch', 'subagent', 'slash_command'] as const
+type ArgRuleTool = (typeof ARG_RULE_TOOLS)[number]
+
+const isArgRuleTool = (name: string): name is ArgRuleTool => (ARG_RULE_TOOLS as readonly string[]).includes(name)
+
 /** The tools, scopes, and path rules accumulated while scanning one grant list. */
 interface GrantAccumulator {
   tools: string[]
   scopedEntries: string[]
-  bashRules: string[]
-  bashUnscoped: boolean
+  argScopes: Record<ArgRuleTool, string[]>
+  argUnscoped: Set<ArgRuleTool>
   pathScopes: Record<PathRuleTool, string[]>
   pathUnscoped: Set<PathRuleTool>
 }
 
 function createGrantAccumulator(): GrantAccumulator {
-  return { tools: [], scopedEntries: [], bashRules: [], bashUnscoped: false, pathScopes: { read: [], edit: [], write: [] }, pathUnscoped: new Set() }
+  return { tools: [], scopedEntries: [], argScopes: { bash: [], web_fetch: [], subagent: [], slash_command: [] }, argUnscoped: new Set(), pathScopes: { read: [], edit: [], write: [] }, pathUnscoped: new Set() }
+}
+
+/** The scopes for one argument-ruled tool, or undefined when it has none or when an
+ * unscoped grant for it makes it wide. The wider grant wins, as it does for bash. */
+function argRules(acc: GrantAccumulator, tool: ArgRuleTool): string[] | undefined {
+  return !acc.argUnscoped.has(tool) && acc.argScopes[tool].length > 0 ? acc.argScopes[tool] : undefined
 }
 
 /** Coerce a raw grant value to its string entries: a YAML list stays a list, a
@@ -186,7 +188,7 @@ function addGrantEntry(acc: GrantAccumulator, item: string): void {
   if (!acc.tools.includes(name)) acc.tools.push(name)
   const open = entry.indexOf('(')
   if (open === -1) {
-    if (name === 'bash') acc.bashUnscoped = true
+    if (isArgRuleTool(name)) acc.argUnscoped.add(name)
     for (const tool of PATH_RULE_TOOLS[name] ?? []) acc.pathUnscoped.add(tool)
     return
   }
@@ -195,7 +197,7 @@ function addGrantEntry(acc: GrantAccumulator, item: string): void {
   // An empty specifier (`Bash()`, `Read()`) matches nothing and must not read as
   // the unscoped grant it explicitly is not: it is recorded so the tool stays
   // restricted, and the matchers treat an empty rule as matching no input.
-  if (name === 'bash') acc.bashRules.push(scope)
+  if (isArgRuleTool(name)) acc.argScopes[name].push(scope)
   for (const tool of PATH_RULE_TOOLS[name] ?? []) acc.pathScopes[tool].push(scope)
 }
 
@@ -217,10 +219,14 @@ function buildPathRules(acc: GrantAccumulator): ToolGrants['pathRules'] {
  *
  * Claude scopes a grant to arguments: `Bash(git add:*)` allows exactly those commands.
  * pi's active-tool list is per tool, with no argument dimension, so the base tool is
- * granted and the scope is kept: commands.ts enforces bash scopes at tool_call time,
- * and the subagent's frontmatter parsing rejects a scoped grant it cannot express.
- * A scope on any other tool is dropped, which widens that grant; bash is the one
- * whose widening reaches everything, so it is the one enforced.
+ * granted and the scope is kept for commands.ts to enforce at tool_call time. Every
+ * specifier Claude documents for an allow rule is kept: `Bash(cmd)`, the Read/Edit
+ * path rules, `WebFetch(domain:host)` and `Agent(AgentName)`. The subagent's own
+ * frontmatter parsing still rejects a scoped grant outright, since it has no
+ * call-time seam to enforce one in.
+ *
+ * Claude's `Tool(param:value)` form is not among them: the permissions reference
+ * confines it to deny and ask rules, and `allowed-tools` is an allow surface.
  */
 export function parseToolGrants(raw: unknown): ToolGrants | undefined {
   const items = coerceGrantItems(raw)
@@ -230,7 +236,10 @@ export function parseToolGrants(raw: unknown): ToolGrants | undefined {
   return {
     tools: acc.tools,
     scopedEntries: acc.scopedEntries,
-    bashRules: !acc.bashUnscoped && acc.bashRules.length > 0 ? acc.bashRules : undefined,
+    bashRules: argRules(acc, 'bash'),
+    domainRules: argRules(acc, 'web_fetch'),
+    agentRules: argRules(acc, 'subagent'),
+    skillRules: argRules(acc, 'slash_command'),
     pathRules: buildPathRules(acc),
   }
 }
@@ -293,6 +302,9 @@ export function parseCommandFile(content: string): ParsedCommand {
     argumentHint: hint(frontmatter['argument-hint']) || undefined,
     allowedTools: grants?.tools,
     bashRules: grants?.bashRules,
+    domainRules: grants?.domainRules,
+    agentRules: grants?.agentRules,
+    skillRules: grants?.skillRules,
     pathRules: grants?.pathRules,
     argumentNames: parseArgumentNames(frontmatter.arguments),
     // A scope on a disallow entry only denies more than asked, so the drop is safe.

package/extensions/internal/mcp-oauth.ts

@@ -18,6 +18,7 @@ import * as path from 'node:path'
 import { getAgentDir } from '@earendil-works/pi-coding-agent'
 import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js'
 import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js'
+import { errorMessage } from './values.js'
 
 interface StoredAuth {
   client?: OAuthClientInformationMixed
@@ -105,6 +106,12 @@ export class FileOAuthProvider implements OAuthClientProvider {
     fs.writeFileSync(this.storePath, JSON.stringify(this.data), { mode: 0o600 })
   }
 
+  /** The configured callbackPort alone, absent when only a remembered port exists.
+   * The caller needs the two apart: a configured port is a hard requirement. */
+  configuredRedirectPort(): number | undefined {
+    return this.oauth?.callbackPort
+  }
+
   /** The configured callbackPort (Claude: for pre-registered redirect URIs), else
    * the port a prior login registered, so a re-login can bind the same one. */
   savedRedirectPort(): number | undefined {
@@ -193,13 +200,19 @@ export class FileOAuthProvider implements OAuthClientProvider {
 /** A one-shot loopback listener for the authorization redirect. Loopback redirect
  * URIs are the RFC 8252 pattern for native apps. A preferred port (from a prior
  * login) is tried first so a re-login keeps the registered redirect_uri; if it is
- * taken, an ephemeral port is used. */
-export async function startCallbackServer(preferredPort?: number): Promise<{ server: http.Server; port: number }> {
+ * taken, an ephemeral port is used.
+ *
+ * `portRequired` marks the port as configured rather than remembered. A configured
+ * `oauth.callbackPort` names the redirect_uri the IdP has registered, so quietly
+ * binding a different one sends the user to an opaque redirect_uri mismatch at the
+ * IdP; the bind failure is reported here instead, where it can name the real cause. */
+export async function startCallbackServer(preferredPort?: number, portRequired = false): Promise<{ server: http.Server; port: number }> {
   const server = http.createServer()
   const listen = (port: number, host: string): Promise<void> => new Promise((resolve, reject) => server.listen(port, host, resolve).once('error', reject))
   try {
     await listen(preferredPort ?? 0, '127.0.0.1')
-  } catch {
+  } catch (error) {
+    if (portRequired) throw new Error(`oauth.callbackPort ${preferredPort} is in use, so the registered redirect URI cannot be served: free that port or change oauth.callbackPort (${errorMessage(error)})`)
     await listen(0, '127.0.0.1')
   }
   const port = (server.address() as { port: number }).port

package/extensions/internal/path-rules.ts

@@ -243,6 +243,23 @@ const toPosix = (target: string): string => {
   return withSlashes.replace(/^\/?[A-Za-z]:\//, '/')
 }
 
+/**
+ * Drop a drive from a RESOLVED rule so it can meet a target that toPosix has already
+ * stripped. Claude documents `//path` as an absolute path from the filesystem root,
+ * and on Windows its own example names the drive as the first segment (`//c/` then a
+ * recursive glob), where `c` is the drive; that resolved to `/c/...` while every target
+ * resolved to `/...`, so the rule could never match anything.
+ *
+ * Windows only, and that is the whole point of the flag: on POSIX `/c/foo` is an
+ * ordinary absolute path and stripping its first segment would widen the rule to
+ * everything under the root. Exported and platform-parameterized rather than reading
+ * process.platform inline, so both branches are assertable from either host.
+ */
+export function stripRuleDrive(rule: string, windows: boolean): string {
+  if (!windows) return rule
+  return rule.replace(/^([A-Za-z]):\//, '/').replace(/^\/[A-Za-z]\//, '/')
+}
+
 export function matchesPathRules(filePath: string, rules: string[], anchors: PathAnchors): boolean {
   const target = toPosix(path.resolve(anchors.cwd, filePath))
   return rules.some((rule) => {
@@ -250,7 +267,7 @@ export function matchesPathRules(filePath: string, rules: string[], anchors: Pat
     // An empty specifier (`Read()`) matches nothing, so the tool stays blocked
     // rather than falling open, mirroring `Bash()`.
     if (trimmed === '') return false
-    const resolved = toPosix(resolveRule(trimmed, anchors))
+    const resolved = stripRuleDrive(toPosix(resolveRule(trimmed, anchors)), path.sep === '\\')
     return new RegExp(`^${globToRegExpSource(resolved)}$`).test(target)
   })
 }

package/extensions/internal/plugins.ts

@@ -215,6 +215,17 @@ export function installedPlugins(home: string, extraSettingsFiles: string[] = []
   return plugins
 }
 
+/** The plugins a managed `enabledPlugins` entry force-enables. Claude exempts their
+ * hooks from `allowManagedHooksOnly`: an administrator who turned a plugin on meant its
+ * hooks to run. Keys are matched the way pluginEnabled matches them, by the qualified
+ * `name@marketplace` or the bare directory name, so the two cannot drift apart. */
+export function managedForceEnabled(plugins: InstalledPlugin[]): InstalledPlugin[] {
+  const managedEntry = readManagedSettings().enabledPlugins
+  if (managedEntry === null || typeof managedEntry !== 'object') return []
+  const entries = managedEntry as Record<string, unknown>
+  return plugins.filter((plugin) => Object.entries(entries).some(([key, value]) => value === true && (key === plugin.name || key.startsWith(`${plugin.name}@`))))
+}
+
 /** The plugin's effective enablement per Claude's precedence: a managed
  * enabledPlugins entry force-enables or blocks, then the user's setting, then the
  * manifest's defaultEnabled, which defaults to true ("starts in an enabled state

package/extensions/internal/scope-rules.ts

@@ -0,0 +1,117 @@
+/**
+ * Claude's argument scopes for the two tools whose specifier is neither a bash
+ * command nor a file path: `WebFetch(domain:host)` and `Agent(AgentName)`.
+ *
+ * pi's active-tool set has no argument dimension, so commands.ts grants the base
+ * tool and checks each call here, the way it already does for `Bash(...)` scopes.
+ * Both matchers fail closed: a scope this module cannot interpret matches nothing
+ * rather than reading as the unscoped grant the author did not write.
+ *
+ * Claude's parameter form `Tool(param:value)` is deliberately absent. The
+ * permissions reference restricts it to deny and ask rules ("An allow rule for one
+ * parameter value wouldn't establish that the call is safe overall, so allow rules
+ * continue to use each tool's own specifier syntax"), and every scope reaching this
+ * module comes from an allow surface: a command's `allowed-tools`.
+ */
+
+/** Regex specials except `*`, which carries the rule's own wildcard meaning. */
+const escapeExceptStar = (text: string): string => text.replaceAll(/[.+?^${}()|[\]\\]/g, String.raw`\$&`)
+
+/** A hostname pattern segment: `*` matches any text that does not cross a dot. */
+const hostPattern = (pattern: string): string => escapeExceptStar(pattern).replaceAll('*', '[^.]*')
+
+/** Lowercased, with the trailing `.` the reference strips from both sides removed. */
+const canonicalHost = (host: string): string => host.trim().toLowerCase().replace(/\.$/, '')
+
+/** The hostname of a fetch target, or '' when the url does not parse. */
+function hostnameOf(url: string): string {
+  try {
+    return canonicalHost(new URL(url).hostname)
+  } catch {
+    return ''
+  }
+}
+
+/** The host pattern of one `domain:` scope, or undefined for any other spelling.
+ * WebFetch has exactly one documented specifier syntax, so an unrecognized scope is
+ * not a wider grant, it is a rule that matches nothing. */
+function domainPattern(rule: string): string | undefined {
+  const trimmed = rule.trim()
+  const colon = trimmed.indexOf(':')
+  if (colon === -1 || trimmed.slice(0, colon).trim().toLowerCase() !== 'domain') return undefined
+  const pattern = canonicalHost(trimmed.slice(colon + 1))
+  return pattern === '' ? undefined : pattern
+}
+
+function matchesDomainRule(host: string, rule: string): boolean {
+  const pattern = domainPattern(rule)
+  if (pattern === undefined) return false
+  if (pattern === '*') return true
+  // A leading `*.` is the one wildcard that crosses dots: it stands for one or more
+  // whole labels, so it covers `a.b.example.com` while leaving the apex unmatched.
+  if (pattern.startsWith('*.')) return new RegExp(String.raw`^(?:[^.]+\.)+${hostPattern(pattern.slice(2))}$`).test(host)
+  return new RegExp(`^${hostPattern(pattern)}$`).test(host)
+}
+
+/**
+ * Claude: "WebFetch rules use a `domain:` prefix and match against the hostname of
+ * the requested URL. Matching is case-insensitive, supports `*` wildcards, and strips
+ * a trailing `.` from both the rule and the hostname."
+ */
+export function matchesDomainRules(url: string, rules: string[]): boolean {
+  const host = hostnameOf(url)
+  if (host === '') return false
+  return rules.some((rule) => matchesDomainRule(host, rule))
+}
+
+/**
+ * Claude: "Permission syntax: `Skill(name)` for exact match, `Skill(name *)` for
+ * prefix match with any arguments."
+ *
+ * The invocation is the skill name and its arguments as one string, the shape pi's
+ * `slash_command` tool takes; a leading `/` is optional there, so it is stripped
+ * before matching. Only the two documented forms are interpreted. A rule spelled any
+ * other way, `commit:*` included, matches nothing rather than widening the grant.
+ */
+export function matchesSkillRules(invocation: string, rules: string[]): boolean {
+  const call = invocation.trim().replace(/^\//, '').trim()
+  if (call === '') return false
+  return rules.some((raw) => {
+    const rule = raw.trim()
+    if (rule === '') return false
+    if (!rule.endsWith(' *')) return rule === call
+    // The space before the trailing `*` is part of the rule, so `review-pr *` covers
+    // `review-pr` and `review-pr 123` but never the longer name `review-pretend`.
+    const prefix = rule.slice(0, -2).trimEnd()
+    return prefix !== '' && (call === prefix || call.startsWith(`${prefix} `))
+  })
+}
+
+/** The `agent` of one call or task entry, when it has one. */
+const agentNameOf = (value: unknown): string | undefined => {
+  const record = value !== null && typeof value === 'object' ? (value as Record<string, unknown>) : undefined
+  return typeof record?.agent === 'string' ? record.agent : undefined
+}
+
+/** Every agent name one subagent call names, across all three modes: `agent` for
+ * single, and the `agent` of each entry in `tasks` (parallel) or `chain` (sequential).
+ * One collector, so a rule checked against single mode cannot be quietly skipped for
+ * the two modes that carry their names in an array. */
+export function agentNamesIn(input: unknown): string[] {
+  const raw = input !== null && typeof input === 'object' ? (input as Record<string, unknown>) : {}
+  const listed = ['tasks', 'chain'].flatMap((key) => (Array.isArray(raw[key]) ? (raw[key] as unknown[]) : []))
+  return [input, ...listed].map(agentNameOf).filter((name): name is string => name !== undefined)
+}
+
+/**
+ * Claude: "Use `Agent(AgentName)` rules to control which subagents Claude can use."
+ *
+ * Every agent the call names must match, not just the first. A subagent call carries
+ * names in `agent`, `tasks[].agent` and `chain[].agent`; gating one field would let
+ * parallel or chain mode route around the rule. A call naming no agent cannot be
+ * checked against the scope, so it fails closed too.
+ */
+export function matchesAgentRules(names: string[], rules: string[]): boolean {
+  if (names.length === 0) return false
+  return names.every((name) => rules.some((rule) => rule.trim() !== '' && rule.trim() === name.trim()))
+}

package/extensions/internal/web-transport.ts

@@ -52,6 +52,13 @@ export function httpFetch(url: URL, opts: TransportOptions): Promise<Response> {
           // (204/205/304) and for status 0. That throw fires here, off the Promise
           // executor, so without this guard it escapes as an uncaughtException and pi
           // exits. Give those statuses a null body; reject anything else that throws.
+          //
+          // The catch below has no test and cannot get one through this function: the
+          // only two throw sources are the null-body statuses, which the line under this
+          // comment handles, and a status outside 200-599, which never reaches this
+          // callback at all (node routes 1xx to the `information` event and rejects a
+          // malformed status line in the parser). It stays as depth, not dead code, but
+          // do not chase its coverage with a test that reaches it some other way.
           const body = NULL_BODY_STATUSES.has(status) ? null : (Readable.toWeb(res) as ReadableStream<Uint8Array>)
           resolve(new Response(body, { status, headers }))
         } catch (err) {

package/extensions/mcp/config.ts

@@ -27,6 +27,8 @@ export interface StdioServerConfig {
   baseName?: string
   /** Root of the plugin that supplied this server; exported as CLAUDE_PLUGIN_ROOT. */
   pluginRoot?: string
+  /** ${CLAUDE_PLUGIN_DATA} for a plugin's server, exported alongside the root. */
+  pluginDataDir?: string
   /** Loaded from the project scope, whose helpers run credential-stripped. */
   projectScope?: boolean
 }
@@ -52,6 +54,8 @@ export interface HttpServerConfig {
   baseName?: string
   /** Root of the plugin that supplied this server; exported as CLAUDE_PLUGIN_ROOT. */
   pluginRoot?: string
+  /** ${CLAUDE_PLUGIN_DATA} for a plugin's server, exported alongside the root. */
+  pluginDataDir?: string
   /** Loaded from the project scope, whose helpers run credential-stripped. */
   projectScope?: boolean
 }
@@ -225,7 +229,7 @@ export function loadPluginServers(plugins: InstalledPlugin[], projectDir?: strin
       // plugin:<plugin-name>:<server-name>", which is what an mcp_tool hook names and what
       // keeps a same-named user server from replacing a plugin's. The tool alias keeps its
       // own flat spelling, mcp__plugin_<plugin>_<server>__<tool>.
-      if (substituted) servers[`plugin:${plugin.name}:${name}`] = { ...substituted, aliasPrefix: `mcp__plugin_${fold(plugin.name)}_${fold(name)}__`, baseName: name, pluginRoot: plugin.root }
+      if (substituted) servers[`plugin:${plugin.name}:${name}`] = { ...substituted, aliasPrefix: `mcp__plugin_${fold(plugin.name)}_${fold(name)}__`, baseName: name, pluginRoot: plugin.root, pluginDataDir: plugin.dataDir }
     }
   }
   return servers

package/extensions/mcp/index.ts

@@ -85,6 +85,10 @@ function authUiFor(ctx: ExtensionContext): AuthUi | undefined {
 
 export default async function mcpExtension(pi: ExtensionAPI) {
   const clients = new Map<string, Client>()
+  // The session's OAuth UI seams, captured at session_start. The reconnect paths below
+  // run outside that handler, and passing undefined there made an INTERACTIVE session
+  // report the headless "cannot log in" advice on a re-auth it could actually perform.
+  let sessionAuthUi: AuthUi | undefined
   const status = new Map<string, { state: string; tools: number }>()
   // Config per server name, kept for call-time timeout tuning: the idle tier follows
   // the transport kind, and a declared per-server timeout governs the wall budget.
@@ -178,14 +182,15 @@ export default async function mcpExtension(pi: ExtensionAPI) {
   /** Claude's mid-session reconnect for a dropped remote server: five attempts with
    * a delay doubling from one second. connectServers redoes the full bring-up
    * (tools, prompts, subscriptions, a fresh onclose) and its duplicate guard skips
-   * out if another path already reconnected the name. Runs without authUi: a server
-   * that now needs a login ends failed, and after the fifth failure the last
-   * attempt's failed status stands, with a session restart as the manual retry. */
+   * out if another path already reconnected the name. Uses the session's authUi, so a
+   * server that now needs a login can prompt for it in an interactive session; headless
+   * still ends failed, and after the fifth failure the last attempt's failed status
+   * stands, with a session restart as the manual retry. */
   async function reconnectWithBackoff(name: string, config: ServerConfig): Promise<void> {
     for (let attempt = 0; attempt < 5; attempt++) {
       await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** attempt))
       if (shuttingDown || clients.has(name)) return
-      await connectServers({ [name]: config }, undefined, true)
+      await connectServers({ [name]: config }, sessionAuthUi, true)
       if (clients.has(name)) return
     }
   }
@@ -200,7 +205,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
       clients.delete(name)
       await withTimeout(old.close(), 3000, 'close').catch(() => {})
     }
-    await connectServers({ [name]: config }, undefined, true)
+    await connectServers({ [name]: config }, sessionAuthUi, true)
   }
 
   /** A tool call with the auth retry: on a 401/403 rejection, reconnect once and
@@ -576,6 +581,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     // project root as CLAUDE_PROJECT_DIR to stdio servers; both derive from ctx.cwd.
     sessionDirs = { projectDir: repoRoot(ctx.cwd) ?? ctx.cwd, launchDir: ctx.cwd }
     const authUi = authUiFor(ctx)
+    sessionAuthUi = authUi
     // The allow/deny lists filter every scope, including a managed-mcp.json set. They
     // merge from managed settings plus the trust-gated settings chain, as Claude
     // documents (a repo's file counts only once the project is approved).

package/extensions/mcp/oauth-flow.ts

@@ -64,7 +64,7 @@ export async function runInteractiveOAuth(name: string, config: { url: string; o
     config.oauth,
     config.url,
   )
-  const { server, port } = await startCallbackServer(provider.savedRedirectPort())
+  const { server, port } = await startCallbackServer(provider.savedRedirectPort(), provider.configuredRedirectPort() !== undefined)
   provider.bindRedirectPort(port)
   try {
     const transport = makeTransport(provider)

package/extensions/mcp/transport.ts

@@ -5,6 +5,7 @@
  */
 
 import { execFile } from 'node:child_process'
+import * as fs from 'node:fs'
 import { pathToFileURL } from 'node:url'
 // SSE is deprecated in favour of Streamable HTTP, but the SDK notes servers still on
 // the old spec exist, so this stays as a fallback for the migration period.
@@ -182,8 +183,8 @@ function helperEnv(name: string, config: HttpServerConfig): NodeJS.ProcessEnv {
 }
 
 /** The env a stdio server process starts with: the SDK allowlist, the config's own
- * env block, and Claude's path variables (CLAUDE_PROJECT_DIR, and CLAUDE_PLUGIN_ROOT
- * for a plugin's server). */
+ * env block, and Claude's three path variables. Claude: "All three are exported as
+ * environment variables to hook processes and to MCP and LSP server subprocesses." */
 function stdioEnv(config: StdioServerConfig, fill: (value: string) => string, session?: SessionDirs): Record<string, string> {
   // CLAUDECODE marks every subprocess; the long-lived server deliberately gets no
   // CLAUDE_CODE_CHILD_SESSION, which Claude reserves for per-call children.
@@ -191,6 +192,16 @@ function stdioEnv(config: StdioServerConfig, fill: (value: string) => string, se
   for (const [key, value] of Object.entries(config.env ?? {})) env[key] = fill(value)
   if (session) env.CLAUDE_PROJECT_DIR = session.projectDir
   if (config.pluginRoot !== undefined) env.CLAUDE_PLUGIN_ROOT = config.pluginRoot
+  // The data dir is "created on first reference"; handing the path to a server is that
+  // reference, so the server does not have to mkdir it before using it.
+  if (config.pluginDataDir !== undefined) {
+    env.CLAUDE_PLUGIN_DATA = config.pluginDataDir
+    try {
+      fs.mkdirSync(config.pluginDataDir, { recursive: true })
+    } catch {
+      // The server still starts; one that needs the directory reports its own failure.
+    }
+  }
   return env
 }
 
@@ -234,7 +245,12 @@ export async function connect(name: string, config: ServerConfig, authUi?: AuthU
     await connectWithTimeout(client, transport, `connect ${name}`)
     return client
   }
-  const url = new URL(fill(config.url))
+  // An absent or blank `url` is a server nobody finished configuring, not a malformed
+  // one. `new URL('')` throws "Invalid URL", which reads as a typo in a real address and
+  // sends people looking for one; name the actual state instead.
+  const rawUrl = fill(config.url ?? '').trim()
+  if (rawUrl === '') throw new Error(`${name} is not configured: it has no url`)
+  const url = new URL(rawUrl)
   if (config.type === 'ws' || config.type === 'websocket') {
     // The SDK's WebSocket transport takes only a url: it carries no headers, bearer
     // token, or headersHelper output. Warn rather than silently dropping configured

package/extensions/skills.ts

@@ -39,6 +39,13 @@ import { errorMessage, isDirectory, isRecord } from './internal/values.js'
  * directory is included only for approved projects: pi's loader surfaces every skill's
  * name and description to the model, so an untrusted repository would otherwise get
  * text into the prompt without the user ever agreeing to load its config. */
+/** The extra skill directories a manifest declares, as a list. A string is one entry,
+ * a list is itself, anything else declares none. */
+function declaredSkillDirs(declared: unknown): string[] {
+  if (Array.isArray(declared)) return declared.map(String)
+  return typeof declared === 'string' ? [declared] : []
+}
+
 export function skillDirs(cwd: string, home: string, trusted: boolean): string[] {
   // Claude's precedence: enterprise (the skills directory beside the managed
   // settings file) overrides personal, and personal overrides project; discovery
@@ -48,9 +55,20 @@ export function skillDirs(cwd: string, home: string, trusted: boolean): string[]
   // skill by its directory, so a plugin skill registers without Claude's
   // /plugin: prefix; a rename-free approximation, disclosed in the README.
   for (const plugin of installedPlugins(home)) {
-    const declared = plugin.manifest.skills
-    const dirs = Array.isArray(declared) ? declared : [typeof declared === 'string' ? declared : 'skills']
+    // Claude: "Adds to the default: `skills`. The default `skills/` directory is always
+    // scanned, and directories listed in `skills` are loaded alongside it." Treating the
+    // declaration as a replacement silently dropped every skill in the conventional
+    // location. (The reference's one exception, a marketplace entry whose source resolves
+    // to the marketplace root, is a marketplace shape pi-code does not model.)
+    const extra = declaredSkillDirs(plugin.manifest.skills)
+    const dirs = [...extra, 'skills']
     candidates.push(...dirs.map((dir) => pluginComponentPath(plugin, String(dir))).filter((dir): dir is string => dir !== undefined))
+    // NOT SUPPORTED: Claude's single-skill layout, "a plugin that ships exactly one skill
+    // can place SKILL.md directly at the plugin root". skillPaths is handed to pi's own
+    // loader, which owns the layout and looks for <dir>/<name>/SKILL.md; adding the plugin
+    // root here does not surface root/SKILL.md and does start scanning every sibling
+    // directory (hooks/, agents/, commands/) for skills. Supporting it needs a loader that
+    // accepts a directory that IS the skill, which is pi's call, not this extension's.
   }
   // Claude loads skills from every .claude/skills between cwd and the repository
   // root; the list goes nearest-first so findClaudeSkill's first match is the

package/extensions/status-line.ts

@@ -352,8 +352,10 @@ export default function statusLine(pi: ExtensionAPI) {
       // Everything below can touch ctx after an await, and every ctx getter throws
       // once the session is disposed. This promise is started from a timer with no
       // awaiter, so an escaping rejection becomes an uncaughtException and exits pi.
-      const result = await runHookCommand(config.command, buildPayload(ctx), COMMAND_TIMEOUT_MS, undefined, undefined, (kill) => {
-        killInflight = kill
+      const result = await runHookCommand(config.command, buildPayload(ctx), COMMAND_TIMEOUT_MS, {
+        onChild: (kill) => {
+          killInflight = kill
+        },
       })
       // Claude: "Your script can output multiple lines to create a richer display."
       // pi has one row for every extension status and replaces newlines with spaces

package/extensions/subagent/index.ts

@@ -56,8 +56,10 @@ export default function subagentExtension(pi: ExtensionAPI) {
 
   const notifyBackgroundCompletion = (run: { id: string; agent: string; state: string; turns: number; output?: string; stderr?: string }): void => {
     // Runs through driveRun's guard, same as the background-mode callback above.
-    // The stop event fires here too, so SubagentStop hooks see resumed runs end.
-    pi.events.emit(SUBAGENT_CHANNEL, { phase: 'stop', agentType: run.agent, agentId: run.id })
+    // The stop event fires here too, so SubagentStop hooks see resumed runs end, and it
+    // carries the run's final assistant text: docs/subagents.md states SubagentStop
+    // receives last_assistant_message unconditionally, and a resumed run is no exception.
+    pi.events.emit(SUBAGENT_CHANNEL, { phase: 'stop', agentType: run.agent, agentId: run.id, lastAssistantMessage: run.output })
     pi.sendMessage({ customType: 'subagent-background', content: backgroundCompletionText(run), display: true }, { triggerTurn: true })
   }
 

package/extensions/thinking.ts

@@ -23,15 +23,21 @@ export function thinkingRank(level: ThinkingLevel): number {
   return Math.max(i, 0)
 }
 
-/** The reasoning level a prompt requests through Claude's think keywords, or undefined
- * when it names none. Checked most-specific first so `think harder` does not fall
- * through to the bare-`think` branch, and on word boundaries so `rethink`/`thinking`
- * and the whole word `ultrathink` never trip the bare match. */
+/** The reasoning level a prompt requests, or undefined when it names none.
+ *
+ * `ultrathink` is the only keyword, per Claude: "Include `ultrathink` anywhere in your
+ * prompt to request deeper reasoning on that turn ... Claude Code passes other phrases
+ * such as 'think', 'think hard', and 'think more' through as ordinary prompt text and
+ * doesn't recognize them as keywords." Escalating on those surprised anyone who merely
+ * used the word in a sentence. Matched on a word boundary so `rethink` and `thinking`
+ * never trip it.
+ *
+ * Divergence: Claude adds an in-context instruction and leaves the API effort level
+ * unchanged. pi has no separate in-context channel for this, and its thinking level IS
+ * how deeper reasoning is requested, so the keyword raises the level for the turn and
+ * restores it after. Same intent, the only mechanism pi has. */
 export function requestedThinkingLevel(text: string): ThinkingLevel | undefined {
-  if (/\bultrathink\b/i.test(text)) return 'max'
-  if (/\bthink harder\b/i.test(text) || /\bthink hard\b/i.test(text)) return 'high'
-  if (/\bthink\b/i.test(text)) return 'medium'
-  return undefined
+  return /\bultrathink\b/i.test(text) ? 'max' : undefined
 }
 
 export default function thinkingExtension(pi: ExtensionAPI) {