pi-code 1.0.13 → 1.0.15

package/extensions/hooks/runners.ts

@@ -0,0 +1,269 @@
+/**
+ * The hook runners: one per hook type (shell command incl. exec-form, http POST,
+ * in-process prompt, mcp_tool call, agent subagent), plus the timeout budget and
+ * the process-group kill used by the shell runner.
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process'
+import type { Api, Model } from '@earendil-works/pi-ai'
+import { runAgent } from '../internal/agent-run.js'
+import { callMcpTool } from '../internal/mcp-call.js'
+import { completeText } from '../internal/model-complete.js'
+import { type HookCommand, httpUrlAllowed, isBackgroundHook } from './config.js'
+
+// Claude defaults to 600s and lets a timed-out hook proceed; here a timed-out
+// PreToolUse or UserPromptSubmit hook fails closed (pi has no permission prompt
+// to fall back on), so ten minutes of default budget would wedge the turn for
+// ten minutes on a hung hook. Hooks that legitimately run long can raise their
+// own per-hook `timeout`.
+const DEFAULT_TIMEOUT_S = 60
+
+export interface HookRunResult {
+  code: number
+  stdout: string
+  stderr: string
+  /** The hook was killed at its timeout, so its exit code carries no verdict. */
+  timedOut: boolean
+  /** The process errored before delivering a verdict (spawn failure, EIO). */
+  spawnFailed?: boolean
+}
+/** Runs one configured hook entry, whatever its type; boundRunner dispatches. */
+export type HookRunner = (hook: HookCommand, payload: unknown, timeoutMs: number) => Promise<HookRunResult>
+/** The shell path specifically; the statusline reuses it for its own command. With an
+ * `args` array it becomes the exec path: `command` is spawned directly with those args.
+ * `onChild` hands the caller a kill for the spawned tree, so a background hook that is
+ * still running at session end can be reaped (Claude kills async hooks at teardown). */
+export type HookCommandRunner = (command: string, payload: unknown, timeoutMs: number, projectDir?: string, args?: string[], onChild?: (kill: () => void) => void) => Promise<HookRunResult>
+
+/** Above 2^31-1 ms Node clamps a timer to 1ms, which would kill the hook instantly. */
+const MAX_TIMEOUT_S = 2_147_483
+
+export function timeoutMs(command: HookCommand): number {
+  // Claude does not enforce `timeout` on an `async` command hook (it does on
+  // `asyncRewake`), so the budget is the Node timer ceiling: the timer exists only
+  // so the delay never clamps, not as a deadline. Still-running background hooks
+  // are killed at session end instead.
+  if (isBackgroundHook(command) && command.asyncRewake !== true) return MAX_TIMEOUT_S * 1000
+  // Non-positive values fall back to the default: a 0ms timer would fire before the
+  // hook runs, and a timed-out PreToolUse hook fails closed, bricking the tool.
+  const declared = command.timeout
+  const seconds = typeof declared === 'number' && declared > 0 ? Math.min(declared, MAX_TIMEOUT_S) : DEFAULT_TIMEOUT_S
+  return seconds * 1000
+}
+
+/** Memory backstop for a runaway hook. A decision payload is orders of magnitude smaller. */
+const MAX_HOOK_OUTPUT = 1_000_000
+
+/** Conventional exit code for a killed-on-timeout command, as `timeout(1)` reports it. */
+const TIMEOUT_EXIT_CODE = 124
+
+/**
+ * Kill the shell and everything it spawned. `sh -c 'a; b'` forks, so signalling the
+ * direct child alone leaves a grandchild alive holding stdout/stderr.
+ */
+function killTree(child: ChildProcess): void {
+  try {
+    // Negative pid targets the whole process group, which `detached` gave the shell.
+    if (child.pid) {
+      process.kill(-child.pid, 'SIGKILL')
+      return
+    }
+  } catch {
+    // Group already reaped, or the platform refused it; fall through to the direct kill.
+  }
+  child.kill('SIGKILL')
+}
+
+export const runHookCommand: HookCommandRunner = (command, payload, timeoutMs, projectDir, args, onChild) =>
+  new Promise((resolve) => {
+    // Absolute path so the shell can't be resolved through an attacker-controlled PATH.
+    // `detached` makes the shell its own process group leader so the timeout can kill
+    // the descendants too. CLAUDE_PROJECT_DIR is Claude's documented way for a hook to
+    // reference project files regardless of the shell's cwd. CLAUDECODE=1 marks every
+    // subprocess Claude spawns, so it is set on the child unconditionally.
+    const env: NodeJS.ProcessEnv = { ...process.env, CLAUDECODE: '1' }
+    if (projectDir) env.CLAUDE_PROJECT_DIR = projectDir
+    // An exec-form hook (an `args` array) spawns the executable directly with those args
+    // and no shell, so shell metacharacters in the args arrive literally; $ARGUMENTS in
+    // each arg is replaced with the event JSON by a replacer function (so $$/$& in the
+    // payload survive verbatim). Without args it stays the shell path. Both share the
+    // same detached process group, so killTree reaches the descendants either way.
+    const file = Array.isArray(args) ? command : '/bin/sh'
+    const spawnArgs = Array.isArray(args) ? args.map((arg) => substituteArguments(arg, payload)) : ['-c', command]
+    const child = spawn(file, spawnArgs, { stdio: ['pipe', 'pipe', 'pipe'], detached: true, env })
+    onChild?.(() => killTree(child))
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    const finish = (result: HookRunResult): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(result)
+    }
+    // Resolve from the timer itself rather than waiting for `close`: `close` fires only
+    // once every stdio pipe is closed, and a grandchild that inherited them can hold the
+    // promise pending long past the timeout, stalling the tool call that awaits it.
+    const timer = setTimeout(() => {
+      killTree(child)
+      finish({ code: TIMEOUT_EXIT_CODE, stdout, stderr, timedOut: true })
+    }, timeoutMs)
+    // Decode on the stream: concatenating Buffers as strings mangles a multi-byte
+    // character split across chunks, and a mangled byte in a hook's deny decision makes
+    // it unparseable, which reads as an allow.
+    child.stdout?.setEncoding('utf8')
+    child.stderr?.setEncoding('utf8')
+    child.stdout?.on('data', (chunk: string) => {
+      if (stdout.length < MAX_HOOK_OUTPUT) stdout += chunk
+    })
+    child.stderr?.on('data', (chunk: string) => {
+      if (stderr.length < MAX_HOOK_OUTPUT) stderr += chunk
+    })
+    child.on('close', (code) => finish({ code: code ?? 0, stdout, stderr, timedOut: false }))
+    // Marked rather than silently read as a clean run: under fd exhaustion a
+    // deny-list guard that never spawned would otherwise pass as an allow.
+    child.on('error', (error) => finish({ code: 0, stdout, stderr: stderr || error.message, timedOut: false, spawnFailed: true }))
+    // A hook that exits without reading stdin (e.g. `exit 2`) closes the pipe first,
+    // so ignore EPIPE on this write rather than crashing the host process.
+    child.stdin?.on('error', () => {})
+    child.stdin?.end(JSON.stringify(payload))
+  })
+
+/** `$VAR` / `${VAR}` in header values, from allowlisted env vars only; a reference
+ * to an unlisted variable becomes an empty string, as Claude documents. */
+function interpolateHeaders(headers: Record<string, string> | undefined, allowed: string[] | undefined): Record<string, string> {
+  const allowedSet = new Set(allowed ?? [])
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(headers ?? {})) {
+    out[key] = value.replace(/\$(?:\{([A-Za-z_]\w*)\}|([A-Za-z_]\w*))/g, (_token, braced?: string, bare?: string) => {
+      const name = braced ?? bare ?? ''
+      return allowedSet.has(name) ? (process.env[name] ?? '') : ''
+    })
+  }
+  return out
+}
+
+/**
+ * Claude's `type: "http"` hook: the payload POSTs as JSON and only a 2xx response
+ * with a valid JSON body renders a decision, read exactly like command stdout.
+ * Everything else, including non-2xx statuses, connection failures and timeouts,
+ * is a non-blocking error by contract, so none of these outcomes ever reports
+ * `timedOut`, which PreToolUse fails closed on. Claude's `allowedHttpHookUrls`
+ * allowlist gates the fetch itself: a URL matching no entry is never contacted,
+ * so a settings file cannot point a hook at an arbitrary endpoint and exfiltrate
+ * the payload; when the setting is absent there are no restrictions, as Claude
+ * documents. A blocked hook renders no decision, like every other http failure.
+ */
+export async function runHttpHook(hook: { type?: string; command: string; url?: string; headers?: Record<string, string>; allowedEnvVars?: string[] }, payload: unknown, timeoutMs: number, allowedUrls?: string[]): Promise<HookRunResult> {
+  const url = hook.url ?? hook.command
+  if (!httpUrlAllowed(url, allowedUrls)) return { code: 1, stdout: '', stderr: `${url} does not match allowedHttpHookUrls; the hook was not called`, timedOut: false }
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...interpolateHeaders(hook.headers, hook.allowedEnvVars) },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    const body = (await response.text()).slice(0, MAX_HOOK_OUTPUT)
+    if (!response.ok) return { code: 1, stdout: '', stderr: `HTTP ${response.status} from ${url}`, timedOut: false }
+    if (body.trim().length === 0) return { code: 0, stdout: '', stderr: '', timedOut: false }
+    try {
+      JSON.parse(body)
+    } catch {
+      return { code: 1, stdout: '', stderr: `non-JSON response from ${url}`, timedOut: false }
+    }
+    return { code: 0, stdout: body, stderr: '', timedOut: false }
+  } catch (error) {
+    return { code: 1, stdout: '', stderr: error instanceof Error ? error.message : String(error), timedOut: false }
+  }
+}
+
+/** System prompt turning a prompt hook into a structured decision, so its reply
+ * flows through interpretHookResult exactly like a command hook's stdout. */
+const PROMPT_HOOK_SYSTEM = [
+  'You are a Claude Code hook evaluating whether an action should proceed.',
+  'Respond with ONLY a JSON object and nothing else:',
+  '{"hookSpecificOutput":{"permissionDecision":"allow"|"deny"|"ask","permissionDecisionReason":"<short reason>"}}',
+  'Use "allow" to let the action proceed, "deny" to block it, "ask" to require the user to confirm.',
+].join('\n')
+
+/**
+ * Claude's `type: "prompt"` hook: the prompt (with `$ARGUMENTS` replaced by the
+ * event JSON) is evaluated by the model, which returns a JSON decision. pi runs it
+ * in-process via completeText and returns the reply as stdout so the existing
+ * decision parser handles it. No model (headless) or a provider error is
+ * non-blocking; only an abort at the timeout fails closed, like the other hooks.
+ */
+/** Replace `$ARGUMENTS` with the event JSON via a replacer function, so `$`-sequences
+ * in the payload (`$$`, `$&`, `` $` ``, `$'`) are inserted literally, not read as
+ * `String.replace` patterns. Prompt and agent hooks feed the result to the model. */
+function substituteArguments(prompt: string | undefined, payload: unknown): string {
+  const json = JSON.stringify(payload)
+  return (prompt ?? '').replaceAll('$ARGUMENTS', () => json)
+}
+
+/** Classify a model/agent failure: the deadline is authoritative via the signal (the
+ * subagent runner rejects with a plain Error on abort, so an error-name check alone
+ * fails open), so a fired signal is a timeout (PreToolUse fails closed); anything else
+ * produced no verdict and is non-blocking. */
+function abortAwareFailure(signal: AbortSignal, error: unknown): HookRunResult {
+  const aborted = signal.aborted || (error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError'))
+  return { code: aborted ? TIMEOUT_EXIT_CODE : 1, stdout: '', stderr: error instanceof Error ? error.message : String(error), timedOut: aborted }
+}
+
+export async function runPromptHook(hook: HookCommand, payload: unknown, model: Model<Api> | undefined, timeoutMs: number): Promise<HookRunResult> {
+  if (!model) return { code: 1, stdout: '', stderr: 'no model available for prompt hook', timedOut: false }
+  // A replacer function, so `$$`/`$&`/`` $` ``/`$'` inside the payload JSON are inserted
+  // verbatim rather than read as replacement patterns (a Bash `echo $$` is a common trigger).
+  const prompt = substituteArguments(hook.prompt, payload)
+  const signal = AbortSignal.timeout(timeoutMs)
+  try {
+    const { text: answer } = await completeText(model, prompt, { system: PROMPT_HOOK_SYSTEM, maxTokens: 512, signal })
+    return { code: 0, stdout: answer, stderr: '', timedOut: false }
+  } catch (error) {
+    return abortAwareFailure(signal, error)
+  }
+}
+
+/**
+ * Claude's `type: "mcp_tool"` hook: call a tool on an already-connected MCP server
+ * and treat its text output like command stdout. pi reaches the server through the
+ * mcp-call seam the mcp extension registers. Like http, it never fails closed: a
+ * missing server, a tool error, or the deadline is non-blocking.
+ */
+export async function runMcpToolHook(hook: HookCommand, payload: unknown, timeoutMs: number): Promise<HookRunResult> {
+  if (!hook.server || !hook.tool) return { code: 1, stdout: '', stderr: 'mcp_tool hook needs server and tool', timedOut: false }
+  const input = hook.input && typeof hook.input === 'object' ? hook.input : (payload as Record<string, unknown>)
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<HookRunResult>((resolve) => {
+    timer = setTimeout(() => resolve({ code: 1, stdout: '', stderr: `mcp_tool hook timed out after ${timeoutMs}ms`, timedOut: false }), timeoutMs)
+  })
+  const call = callMcpTool(hook.server, hook.tool, input)
+    .then((result): HookRunResult => ({ code: result.isError ? 1 : 0, stdout: result.text, stderr: '', timedOut: false }))
+    .catch((error): HookRunResult => ({ code: 1, stdout: '', stderr: error instanceof Error ? error.message : String(error), timedOut: false }))
+  try {
+    return await Promise.race([call, deadline])
+  } finally {
+    // Left running, the deadline timer pins the event loop for the full timeout
+    // after the call resolves, delaying exit in a one-shot headless run.
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Claude's experimental `type: "agent"` hook: spawn a subagent (Read/Grep/Glob) to
+ * verify a condition, then return its final text as a JSON decision, parsed by the
+ * same interpreter as a command hook. pi reaches the subagent through the agent-run
+ * seam the subagent extension registers. Like the prompt hook, only an abort at the
+ * deadline fails closed; a missing runner or a crashed agent is non-blocking.
+ */
+export async function runAgentHook(hook: HookCommand, payload: unknown, timeoutMs: number, sessionModelId: string | undefined): Promise<HookRunResult> {
+  const prompt = substituteArguments(hook.prompt, payload)
+  const signal = AbortSignal.timeout(timeoutMs)
+  try {
+    const answer = await runAgent({ prompt, model: hook.model ?? sessionModelId, systemPrompt: hook.systemPrompt, signal })
+    return { code: 0, stdout: answer, stderr: '', timedOut: false }
+  } catch (error) {
+    return abortAwareFailure(signal, error)
+  }
+}

package/extensions/internal/command-file.ts

@@ -107,7 +107,7 @@ export function normalizeToolName(name: string): string {
  * Scanned rather than matched with a regex: the pattern form is quadratic on an input
  * of unclosed parens, and a command file comes from the repository.
  */
-export function toolEntries(raw: string): string[] {
+function toolEntries(raw: string): string[] {
   const entries: string[] = []
   let current = ''
   let depth = 0

package/extensions/internal/managed-settings.ts

@@ -26,6 +26,11 @@ export function setManagedSettingsPath(file?: string): void {
   managedSettingsFileOverride = file
 }
 
+/** The managed-settings.json path in effect, honoring the test-seam override. */
+export function managedSettingsFile(): string {
+  return managedSettingsFileOverride ?? managedSettingsPath()
+}
+
 /** The parsed managed settings object, or {} when absent or malformed. */
 export function readManagedSettings(file: string = managedSettingsFileOverride ?? managedSettingsPath()): Record<string, unknown> {
   try {

package/extensions/internal/output-guard.ts

@@ -19,7 +19,7 @@ import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from '
  * Shorter input comes back whole and a negative budget yields nothing, so callers
  * need no length check of their own.
  */
-export function sliceBytes(text: string, maxBytes: number): string {
+function sliceBytes(text: string, maxBytes: number): string {
   return Buffer.from(text, 'utf-8').subarray(0, Math.max(0, maxBytes)).toString('utf-8')
 }
 

package/extensions/internal/settings-chain.ts

@@ -0,0 +1,24 @@
+/**
+ * The shared Claude settings chain: the ordered settings.json files a home-and-project
+ * setting is read from, newest winning. User settings always lead; the project's
+ * settings.json and settings.local.json (each the nearest of its name at or above cwd,
+ * falling back to cwd's own `.claude/`) follow only when the project is included, the
+ * trust gate every caller applies. Hooks, output styles, memory, the CLAUDE.md excludes,
+ * and the skill-shell policy all resolve their files through this one chain.
+ */
+
+import * as path from 'node:path'
+import { claudeConfigDir } from './config-dir.js'
+import { findNearestFile } from './project-root.js'
+
+/** The user settings.json, then (only when `includeProject`) the nearest project
+ * settings.json and settings.local.json at or above cwd, with cwd's own `.claude/` as
+ * the fallback for each. Later files win. */
+export function claudeSettingsChain(cwd: string, home: string, includeProject: boolean): string[] {
+  const files = [path.join(claudeConfigDir(home), 'settings.json')]
+  if (!includeProject) return files
+  for (const name of ['settings.json', 'settings.local.json']) {
+    files.push(findNearestFile(cwd, path.join('.claude', name)) ?? path.join(cwd, '.claude', name))
+  }
+  return files
+}

package/extensions/internal/stat-token.ts

@@ -0,0 +1,14 @@
+/**
+ * A cheap freshness token for a file: its mtime and size joined, so a same-mtime rewrite
+ * of a different length still invalidates. The per-turn caches that stat a file instead of
+ * re-reading it (the CLAUDE.md import memo, the memory index cache) compare this token.
+ * Throws when the file cannot be stat'd; callers that treat "missing" as a value catch it.
+ */
+
+import * as fs from 'node:fs'
+
+/** `${mtimeMs}:${size}` for `file`. Throws if the file cannot be stat'd. */
+export function statToken(file: string): string {
+  const stat = fs.statSync(file)
+  return `${stat.mtimeMs}:${stat.size}`
+}

package/extensions/internal/turn-override.ts

@@ -0,0 +1,73 @@
+/**
+ * A per-turn value override: capture the prior value once, restore it when the turn
+ * settles. This is the shape shared by commands.ts's `model:`/`effort:` overrides and
+ * thinking.ts's keyword escalation. Each captures what to restore the first time a turn
+ * overrides (so back-to-back overrides in one turn still restore the original session
+ * value, not an intermediate one), drops that capture without restoring at a session
+ * boundary, and restores on settle.
+ *
+ * A conditional override restores only when the current value still equals the target it
+ * moved to, so a later owner (another extension's restore, a manual change) is not
+ * clobbered; a current that cannot be read restores unconditionally, the best-effort the
+ * consumers relied on. The escalating set itself stays at the call site, since who reads
+ * "current" and how the value is applied (sync, async-with-catch) differ per consumer.
+ */
+
+export interface TurnOverride<T> {
+  /** The value to restore, captured only on the first arm of a turn; undefined when
+   * nothing is armed. */
+  readonly prior: T | undefined
+  /** The value last armed as the move target, for a conditional restore. */
+  readonly target: T | undefined
+  /** Record the value to restore (kept only the first time per turn) and, optionally, the
+   * value moved to for a conditional restore. Does not apply the override. */
+  arm(prior: T, target?: T): void
+  /** Drop the pending capture without restoring: a session boundary. */
+  reset(): void
+  /** Restore the captured prior via `set` and clear the capture. A conditional override
+   * stands down when the current value has moved off the target. No-op when nothing is
+   * armed. */
+  settle(): void
+}
+
+export function createTurnOverride<T>(opts: {
+  /** Applies the restore value. Consumers wrap their setter here (async-with-catch for
+   * commands' model, plain for the thinking level). */
+  set: (value: T) => void
+  /** Reads the current value, for a conditional restore. Only consulted when
+   * `conditional` is set. */
+  get?: () => T | undefined
+  /** When set, restore only if the current value still equals the armed target. */
+  conditional?: boolean
+}): TurnOverride<T> {
+  let prior: T | undefined
+  let target: T | undefined
+  return {
+    get prior() {
+      return prior
+    },
+    get target() {
+      return target
+    },
+    arm(priorValue, targetValue) {
+      prior = prior ?? priorValue
+      target = targetValue
+    },
+    reset() {
+      prior = undefined
+      target = undefined
+    },
+    settle() {
+      if (prior === undefined) return
+      const restore = prior
+      const movedTo = target
+      prior = undefined
+      target = undefined
+      if (opts.conditional) {
+        const current = opts.get?.()
+        if (current !== undefined && current !== movedTo) return
+      }
+      opts.set(restore)
+    },
+  }
+}

package/extensions/mcp/config.ts

@@ -0,0 +1,159 @@
+/**
+ * MCP server configuration: the config types, ${VAR} interpolation, the user and
+ * project config paths and their loading, and the servers declared by plugins.
+ */
+
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { claudeConfigDir } from '../internal/config-dir.js'
+import { type InstalledPlugin, substitutePluginVars } from '../internal/plugins.js'
+import { findNearestFile } from '../internal/project-root.js'
+
+export interface StdioServerConfig {
+  type?: 'stdio'
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+  /** Per-call wall-clock budget in ms, overriding MCP_TOOL_TIMEOUT for this server. */
+  timeout?: number
+  /** Plugin servers alias their tools mcp__plugin_<plugin>_<server>__<tool>. */
+  aliasPrefix?: string
+}
+
+export interface HttpServerConfig {
+  type?: 'http' | 'streamable-http' | 'sse' | 'ws' | 'websocket'
+  url: string
+  headers?: Record<string, string>
+  bearerToken?: string
+  bearerTokenEnv?: string
+  /** A command whose JSON stdout is merged into the connect headers, for auth
+   * schemes other than OAuth/static tokens (Claude's headersHelper). */
+  headersHelper?: string
+  /** Per-call wall-clock budget in ms, overriding MCP_TOOL_TIMEOUT for this server. */
+  timeout?: number
+  /** Plugin servers alias their tools mcp__plugin_<plugin>_<server>__<tool>. */
+  aliasPrefix?: string
+}
+
+export type ServerConfig = StdioServerConfig | HttpServerConfig
+
+/** Claude's .mcp.json expansion: ${VAR}, and ${VAR:-default}. The syntax borrows
+ * shell's `:-`, which substitutes when the variable is unset OR empty. */
+export function interpolateEnv(value: string, env: NodeJS.ProcessEnv = process.env, onMissing?: (name: string) => void): string {
+  return value.replace(/\$\{(\w+)(:-([^}]*))?\}/g, (fullMatch, name, hasDefault, fallback) => {
+    const current = env[name]
+    if (hasDefault !== undefined) return current || fallback
+    if (current === undefined) {
+      // A referenced variable with no value and no default: keep the literal ${VAR} and
+      // report it, matching Claude, rather than silently substituting an empty string that
+      // turns `Bearer ${TOKEN}` into a confusing `Bearer ` and a mystery 401.
+      onMissing?.(name)
+      return fullMatch
+    }
+    return current
+  })
+}
+
+/** The user's ~/.claude.json (top-level mcpServers plus the per-project `projects` map).
+ * When CLAUDE_CONFIG_DIR is set, Claude relocates .claude.json inside that directory; by
+ * default it stays at the home root, since .claude.json does NOT live inside ~/.claude. A
+ * blank value is treated as unset, matching claudeConfigDir. */
+function claudeJsonPath(home: string): string {
+  const override = process.env.CLAUDE_CONFIG_DIR
+  return override && override.trim().length > 0 ? path.join(claudeConfigDir(home), '.claude.json') : path.join(home, '.claude.json')
+}
+
+/** User-scoped MCP config (the user's own; safe to load without project trust). The .pi
+ * tree is pi's own and is not relocated by CLAUDE_CONFIG_DIR. */
+export function userConfigPaths(home: string): string[] {
+  return [claudeJsonPath(home), path.join(home, '.pi', 'agent', 'mcp.json')]
+}
+
+/** Project-scoped MCP config, each file the nearest of its name at or above cwd
+ * (bounded at the repository root, matching the approval walk). Loaded only for
+ * trusted projects: a server's `command` runs on connect. */
+export function projectConfigPaths(cwd: string): string[] {
+  return ['.mcp.json', path.join('.pi', 'mcp.json')].map((rel) => findNearestFile(cwd, rel) ?? path.join(cwd, rel))
+}
+
+export function loadConfigFrom(files: string[]): Record<string, ServerConfig> {
+  const servers: Record<string, ServerConfig> = {}
+  for (const file of files) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
+      Object.assign(servers, parsed.mcpServers ?? {})
+    } catch {
+      // missing or invalid file: skip silently, /mcp reports what loaded
+    }
+  }
+  return servers
+}
+
+/**
+ * All user-owned servers for this session: the global user servers plus Claude's "local"
+ * scope, the per-project user servers under `projects[cwd].mcpServers` in ~/.claude.json.
+ * Both are the user's own config, so neither needs project trust; local wins on a name
+ * clash (Claude's precedence is local over user).
+ */
+export function loadUserScope(home: string, cwd: string): Record<string, ServerConfig> {
+  const servers = loadConfigFrom(userConfigPaths(home))
+  try {
+    const claudeJson = JSON.parse(fs.readFileSync(claudeJsonPath(home), 'utf-8'))
+    Object.assign(servers, claudeJson.projects?.[cwd]?.mcpServers ?? {})
+  } catch {
+    // missing or invalid ~/.claude.json: the top-level user servers already loaded
+  }
+  return servers
+}
+
+/** The mcpServers one plugin declares: an inline map on the manifest, or the file it
+ * points to (default .mcp.json at the plugin root), with ${CLAUDE_PLUGIN_*} substituted
+ * before parsing. Malformed or missing JSON yields no entries. */
+function pluginServerEntries(plugin: InstalledPlugin): Record<string, ServerConfig> {
+  const declared = plugin.manifest.mcpServers
+  // An inline map of name -> config; an array is not a valid mcpServers map (it
+  // would register a server named '0'), so it falls through to the path branch.
+  if (declared !== null && typeof declared === 'object' && !Array.isArray(declared)) {
+    try {
+      return JSON.parse(substitutePluginVars(JSON.stringify(declared), plugin))
+    } catch {
+      return {}
+    }
+  }
+  const file = path.resolve(plugin.root, typeof declared === 'string' ? declared : '.mcp.json')
+  try {
+    const parsed = JSON.parse(substitutePluginVars(fs.readFileSync(file, 'utf-8'), plugin))
+    return parsed.mcpServers ?? {}
+  } catch {
+    return {}
+  }
+}
+
+/** Servers shipped by enabled plugins (.mcp.json or the manifest's `mcpServers`,
+ * inline or by path), with ${CLAUDE_PLUGIN_*} substituted before parsing. Their
+ * tools alias as mcp__plugin_<plugin>_<server>__<tool> for hook matchers, as
+ * Claude scopes them. */
+export function loadPluginServers(plugins: InstalledPlugin[]): Record<string, ServerConfig> {
+  const fold = (name: string): string => name.replaceAll('-', '_')
+  const servers: Record<string, ServerConfig> = {}
+  for (const plugin of plugins) {
+    for (const [name, config] of Object.entries(pluginServerEntries(plugin))) {
+      servers[name] = { ...config, aliasPrefix: `mcp__plugin_${fold(plugin.name)}_${fold(name)}__` }
+    }
+  }
+  return servers
+}
+
+/** A server cwd expands ${VAR} then a leading ~, or stays unset. */
+export function expandCwd(cwd: string | undefined): string | undefined {
+  if (!cwd) return undefined
+  return interpolateEnv(cwd).replace(/^~(?=\/|$)/, os.homedir())
+}
+
+export function warnOnTypelessUrl(name: string, config: ServerConfig): void {
+  if ('url' in config && config.type === undefined) {
+    console.warn(`pi-code-mcp: server ${name} declares a url with no "type"; add "type": "http" or "sse"`)
+  }
+}