pi-code 1.0.8 → 1.0.10

package/extensions/mcp.ts

@@ -48,6 +48,7 @@ import { WebSocketClientTransport } from '@modelcontextprotocol/sdk/client/webso
 import { PromptListChangedNotificationSchema, ResourceListChangedNotificationSchema, ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js'
 import { Type } from 'typebox'
 import { splitArgs } from './internal/command-file.js'
+import { claudeConfigDir } from './internal/config-dir.js'
 import { MCP_TOOLS_CHANNEL, type McpToolAlias } from './internal/mcp-alias.js'
 import { setMcpToolCaller } from './internal/mcp-call.js'
 import { FileOAuthProvider, openBrowser, startCallbackServer, waitForAuthCode } from './internal/mcp-oauth.js'
@@ -57,7 +58,14 @@ import { isProjectApproved, isProjectApprovedSilently } from './internal/project
 import { findNearestFile } from './internal/project-root.js'
 
 const DEFAULT_CONNECT_TIMEOUT_MS = 10_000
-const DEFAULT_CALL_TIMEOUT_MS = 120_000
+// Claude's MCP_TOOL_TIMEOUT default is effectively hours: the per-call wall-clock budget
+// is only a ceiling, and the idle timeout below is the real guard. 4h matches that model,
+// so a legitimately slow-but-progressing tool is not killed at the old 2 minutes.
+const DEFAULT_CALL_TIMEOUT_MS = 14_400_000
+// The idle timeout: the longest a call may go with no response or progress before it is
+// abandoned. Claude uses a separate idle guard (minutes) rather than the hours-long
+// wall-clock budget; the SDK resets this window on every progress notification.
+const DEFAULT_CALL_IDLE_TIMEOUT_MS = 300_000
 
 /** A positive-integer env override, or the default when unset or unparseable. */
 function envTimeout(name: string, fallback: number): number {
@@ -70,6 +78,33 @@ function envTimeout(name: string, fallback: number): number {
 // Claude honors MCP_TIMEOUT (connect) and MCP_TOOL_TIMEOUT (per-call), both in ms.
 const connectTimeoutMs = (): number => envTimeout('MCP_TIMEOUT', DEFAULT_CONNECT_TIMEOUT_MS)
 const callTimeoutMs = (): number => envTimeout('MCP_TOOL_TIMEOUT', DEFAULT_CALL_TIMEOUT_MS)
+
+/** The idle timeout in ms: the longest a call may go with no response or progress before
+ * it is abandoned, overridable by CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT, with 0 disabling it
+ * (leaving only the wall-clock budget). Unlike envTimeout, an explicit 0 is honored as
+ * "disabled" rather than falling back to the default. */
+function idleTimeoutMs(): number {
+  const raw = process.env.CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT
+  if (raw === undefined) return DEFAULT_CALL_IDLE_TIMEOUT_MS
+  const value = Number.parseInt(raw, 10)
+  if (value === 0) return 0
+  return Number.isInteger(value) && value > 0 ? value : DEFAULT_CALL_IDLE_TIMEOUT_MS
+}
+
+/** The SDK RequestOptions for a call under pi's two-tier timeout: a wall-clock ceiling and,
+ * under it, an idle timeout the SDK resets on every progress notification. When the idle
+ * window is enabled and tighter than the wall budget, `timeout` is that per-quiet-period
+ * deadline (resetTimeoutOnProgress), maxTotalTimeout caps the wall clock, and an onprogress
+ * handler is required: it makes the server address progress to this request and lets the
+ * SDK reset the timer on it. When the idle timeout is disabled, or already looser than the
+ * wall budget, only the wall budget applies. The outer withTimeout race is a wall-clock
+ * backstop and must be raced against `wall`, never the idle window, so a legitimately
+ * progressing call is not cut off. */
+function callRequestOptions(wall: number): { timeout: number; resetTimeoutOnProgress?: boolean; maxTotalTimeout?: number; onprogress?: () => void } {
+  const idle = idleTimeoutMs()
+  if (idle === 0 || idle >= wall) return { timeout: wall }
+  return { timeout: idle, resetTimeoutOnProgress: true, maxTotalTimeout: wall, onprogress: () => {} }
+}
 // Tool names an MCP server must never take over. formatToolName always emits
 // `<server>_<tool>`, so only names containing an underscore are actually reachable:
 // pi's own built-ins (read, bash, edit, ...) cannot be produced and are not listed.
@@ -125,9 +160,19 @@ export function interpolateEnv(value: string, env: NodeJS.ProcessEnv = process.e
   })
 }
 
-/** User-scoped MCP config (the user's own; safe to load without project trust). */
+/** 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 [path.join(home, '.claude.json'), path.join(home, '.pi', 'agent', 'mcp.json')]
+  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
@@ -163,7 +208,7 @@ export function projectServerPolicy(cwd: string, home: string, projectApproved:
     }
   }
   const names = (value: unknown): string[] => (Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [])
-  const userSettings = read(path.join(home, '.claude', 'settings.json'))
+  const userSettings = read(path.join(claudeConfigDir(home), 'settings.json'))
   const projectSettings = read(findNearestFile(cwd, path.join('.claude', 'settings.json')) ?? path.join(cwd, '.claude', 'settings.json'))
   const localSettings = read(findNearestFile(cwd, path.join('.claude', 'settings.local.json')) ?? path.join(cwd, '.claude', 'settings.local.json'))
   const disabled = new Set([...names(userSettings.disabledMcpjsonServers), ...names(projectSettings.disabledMcpjsonServers), ...names(localSettings.disabledMcpjsonServers)])
@@ -208,7 +253,7 @@ export function loadConfigFrom(files: string[]): Record<string, ServerConfig> {
 export function loadUserScope(home: string, cwd: string): Record<string, ServerConfig> {
   const servers = loadConfigFrom(userConfigPaths(home))
   try {
-    const claudeJson = JSON.parse(fs.readFileSync(path.join(home, '.claude.json'), 'utf-8'))
+    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
@@ -321,6 +366,47 @@ export function mcpAllowDeny(managedFile: string = managedSettingsFileOverride ?
   }
 }
 
+/** The managed-mcp.json path: a sibling of managed-settings.json (same directory). Derived
+ * through the same test seam so a test can write both into one temp dir. */
+export function managedMcpPath(managedFile: string = managedSettingsFileOverride ?? managedSettingsPath()): string {
+  return path.join(path.dirname(managedFile), 'managed-mcp.json')
+}
+
+/** Claude's managed-mcp.json: when it exists beside managed-settings.json it takes
+ * exclusive control of MCP. Only its `mcpServers` load; user, project, and plugin servers
+ * are all suppressed (and the project-approval flow with them), and an empty map disables
+ * MCP entirely. Returns the managed server map (possibly empty) when the file exists and
+ * parses, or null only when the file is absent, in which case MCP loads from the usual
+ * scopes exactly as before. A file that parses but carries no `mcpServers` object is an
+ * empty managed set, so a deployed-but-bodyless policy locks down rather than silently
+ * reopening the other scopes. A file that is PRESENT but not valid JSON fails closed to
+ * the same empty set (deny-all) rather than reopening those scopes: the lockdown intent
+ * means a corrupt or truncated policy file must not become an allow-all. The allow/deny
+ * lists still filter the returned set. */
+export function loadManagedMcpServers(managedFile: string = managedSettingsFileOverride ?? managedSettingsPath()): Record<string, ServerConfig> | null {
+  const file = managedMcpPath(managedFile)
+  let raw: string
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch {
+    // Absent (or unreadable) managed-mcp.json: no managed MCP control, load normally.
+    return null
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    // Present but corrupt: fail closed to an empty managed set, exactly like an empty map,
+    // rather than reopening the user/project/plugin scopes.
+    console.warn(`pi-code-mcp: managed-mcp.json is present but not valid JSON (${file}); failing closed to no MCP servers: ${error instanceof Error ? error.message : String(error)}`)
+    return {}
+  }
+  if (parsed === null || typeof parsed !== 'object') return {}
+  const servers = (parsed as { mcpServers?: unknown }).mcpServers
+  if (servers === null || typeof servers !== 'object' || Array.isArray(servers)) return {}
+  return servers as Record<string, ServerConfig>
+}
+
 /** Claude's managed allow/deny lists: `allowed` null means no allow list (keep all);
  * a set (even empty) is exclusive, so only its members survive; a deny list removes
  * servers on top, deny winning over allow. */
@@ -649,6 +735,23 @@ type HttpFamilyTransport = SSEClientTransport | StreamableHTTPClientTransport //
 
 type MakeTransport = (authProvider?: OAuthClientProvider) => HttpFamilyTransport
 
+/** Interactive OAuth logins block on a confirm dialog and open a browser tab, so two
+ * at once (a user-scope and a consented project-scope server both 401ing, connecting in
+ * parallel) would stack dialogs and browser tabs. This chains them so a second
+ * interactive login waits for the first to settle; the tail is reset to a resolved
+ * promise regardless of outcome, so a failed login never poisons the queue. Silent
+ * (stored-token) connects do not pass through here and stay fully parallel. */
+let oauthQueue: Promise<unknown> = Promise.resolve()
+
+function serializeInteractiveOAuth<T>(run: () => Promise<T>): Promise<T> {
+  const result = oauthQueue.then(run, run)
+  oauthQueue = result.then(
+    () => {},
+    () => {},
+  )
+  return result
+}
+
 /**
  * Connect an http-family server, running Claude's OAuth login when the server
  * demands one. Stored tokens ride the first attempt so the SDK refreshes
@@ -671,7 +774,7 @@ async function connectHttpFamily(name: string, config: { url: string }, makeTran
   } catch (error) {
     if (bearerToken || !isUnauthorized(error)) throw error
     if (!authUi) throw new OAuthRequiredError(`${name} requires a login; run pi interactively to authenticate`)
-    return await runInteractiveOAuth(name, config, makeTransport, label, authUi, newClient)
+    return await serializeInteractiveOAuth(() => runInteractiveOAuth(name, config, makeTransport, label, authUi, newClient))
   }
 }
 
@@ -782,7 +885,7 @@ function resourceTemplateEntry(server: string, template: { uriTemplate: string;
 async function collectResources(entries: Array<Record<string, unknown>>, name: string, client: Client, budget: number): Promise<void> {
   let cursor: string | undefined
   do {
-    const page = await withTimeout(client.listResources({ cursor }, { timeout: budget }), budget, `list resources ${name}`)
+    const page = await withTimeout(client.listResources({ cursor }, callRequestOptions(budget)), budget, `list resources ${name}`)
     for (const resource of page.resources) entries.push(resourceEntry(name, resource))
     cursor = page.nextCursor
   } while (cursor)
@@ -792,7 +895,7 @@ async function collectResources(entries: Array<Record<string, unknown>>, name: s
 async function collectResourceTemplates(entries: Array<Record<string, unknown>>, name: string, client: Client, budget: number): Promise<void> {
   let cursor: string | undefined
   do {
-    const page = await withTimeout(client.listResourceTemplates({ cursor }, { timeout: budget }), budget, `list resource templates ${name}`)
+    const page = await withTimeout(client.listResourceTemplates({ cursor }, callRequestOptions(budget)), budget, `list resource templates ${name}`)
     for (const template of page.resourceTemplates) entries.push(resourceTemplateEntry(name, template))
     cursor = page.nextCursor
   } while (cursor)
@@ -828,7 +931,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
   setMcpToolCaller(async (server, tool, input) => {
     const client = clients.get(server)
     if (!client) throw new Error(`MCP server "${server}" is not connected`)
-    const result = await client.callTool({ name: tool, arguments: input }, undefined, { timeout: callTimeoutMs() })
+    const result = await client.callTool({ name: tool, arguments: input }, undefined, callRequestOptions(callTimeoutMs()))
     const text = mapContent(result.content as McpContentBlock[], result.structuredContent)
       .filter((part): part is { type: 'text'; text: string } => part.type === 'text')
       .map((part) => part.text)
@@ -866,12 +969,15 @@ export default async function mcpExtension(pi: ExtensionAPI) {
           // and this closure would otherwise keep calling the old, closed client.
           const current = clients.get(name)
           if (!current) throw new Error(`MCP server "${name}" is not connected`)
-          // Pass the timeout to the SDK too: its own default request timeout is 60s and
-          // would otherwise reject first, so the outer race at CALL_TIMEOUT_MS was dead.
-          // Claude's per-server timeout wins over MCP_TOOL_TIMEOUT, with a 1s floor.
+          // The per-server timeout (Claude's, 1s floor) or MCP_TOOL_TIMEOUT is the
+          // wall-clock ceiling; callRequestOptions layers the idle timeout under it, which
+          // the SDK enforces (resetting on progress). Pass the options to the SDK too: its
+          // own default request timeout is 60s and would otherwise reject first. The outer
+          // race uses the wall budget, never the idle window, so a progressing call is not
+          // cut off at the idle timeout.
           const declared = typeof config.timeout === 'number' && config.timeout >= 1000 ? config.timeout : undefined
-          const budget = declared ?? callTimeoutMs()
-          const result = await withTimeout(current.callTool({ name: tool.name, arguments: params as Record<string, unknown> }, undefined, { timeout: budget }), budget, toolName)
+          const wall = declared ?? callTimeoutMs()
+          const result = await withTimeout(current.callTool({ name: tool.name, arguments: params as Record<string, unknown> }, undefined, callRequestOptions(wall)), wall, toolName)
           const content = mapContent(result.content as McpContentBlock[], result.structuredContent)
           const details: { error?: string } = {}
           if (result.isError) {
@@ -923,8 +1029,8 @@ export default async function mcpExtension(pi: ExtensionAPI) {
             const promptArgs = mapPromptArguments(prompt.arguments, args)
             const params: { name: string; arguments?: Record<string, string> } = { name: prompt.name }
             if (Object.keys(promptArgs).length > 0) params.arguments = promptArgs
-            const budget = callTimeoutMs()
-            const result = await withTimeout(current.getPrompt(params, { timeout: budget }), budget, commandName)
+            const wall = callTimeoutMs()
+            const result = await withTimeout(current.getPrompt(params, callRequestOptions(wall)), wall, commandName)
             // The prompt drives a turn exactly the way a custom slash command does
             // (see commands.ts), carrying its image blocks through. A prompt that
             // yields no content is reported rather than sent as an empty turn.
@@ -1010,8 +1116,8 @@ export default async function mcpExtension(pi: ExtensionAPI) {
         const { server, uri } = params as { server: string; uri: string }
         const client = clients.get(server)
         if (!client) throw new Error(`MCP server "${server}" is not connected`)
-        const budget = callTimeoutMs()
-        const result = await withTimeout(client.readResource({ uri }, { timeout: budget }), budget, `read ${uri}`)
+        const wall = callTimeoutMs()
+        const result = await withTimeout(client.readResource({ uri }, callRequestOptions(wall)), wall, `read ${uri}`)
         const blocks = (result.contents as Array<{ uri: string; text?: string; blob?: string; mimeType?: string }>).map((entry): McpContentBlock => {
           if (typeof entry.text === 'string') return { type: 'resource', resource: { uri: entry.uri, text: entry.text } }
           if (entry.blob && entry.mimeType?.startsWith('image/')) return { type: 'image', data: entry.blob, mimeType: entry.mimeType }
@@ -1113,17 +1219,11 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     )
   }
 
-  /** Connect the project scope under the per-server policy. Returns whether the scope
-   * is settled, so a refused confirm can be retried on a later session start. */
-  async function connectProjectScope(ctx: ExtensionContext): Promise<boolean> {
-    // The stored decision, read without prompting: consent recorded inside the
-    // project only counts once the project itself has been approved.
-    const approved = isProjectApprovedSilently(ctx)
-    const policy = projectServerPolicy(ctx.cwd, os.homedir(), approved)
-    const { allowed, denied } = mcpAllowDeny()
-    const { consented, gated } = splitByPolicy(applyServerPolicy(loadConfigFrom(projectConfigPaths(ctx.cwd)), allowed, denied), policy)
-    const authUi = authUiFor(ctx)
-    if (Object.keys(consented).length > 0) await connectServers(consented, authUi)
+  /** Connect the approval-gated project servers, behind the whole-project confirm.
+   * Returns whether the scope is settled, so a refused confirm can be retried on a
+   * later session start. The consented half of the project scope connects earlier,
+   * concurrently with the user scope, from session_start itself. */
+  async function connectGatedProjectServers(ctx: ExtensionContext, gated: Record<string, ServerConfig>, authUi?: AuthUi): Promise<boolean> {
     if (Object.keys(gated).length === 0) return true
     if (!(await isProjectApproved(ctx))) return false
     await connectServers(gated, authUi)
@@ -1132,15 +1232,32 @@ export default async function mcpExtension(pi: ExtensionAPI) {
 
   let projectConnected = false
 
-  pi.on('session_start', async (_event, ctx) => {
-    // Connecting spawns processes and opens sockets, so it belongs here rather than in
-    // the factory: pi runs the factory for invocations that never start a session.
-    // Names still connected are filtered out, so a later session start only retries
-    // servers that failed or whose transport dropped, without duplicate-name warnings.
+  /** managed-mcp.json exclusive mode: a policy deployed mid-process must not leave
+   * already-connected user/project servers running alongside the managed set. Evict every
+   * connected client not in the managed set (delete it from the map first so the onclose
+   * handler's guard sees it gone and does not overwrite the status, then close it
+   * best-effort and mark it disabled), then connect only the managed servers. */
+  async function connectManagedExclusive(managed: Record<string, ServerConfig>, allowed: Set<string> | null, denied: Set<string>, authUi?: AuthUi): Promise<void> {
+    const managedServers = applyServerPolicy(managed, allowed, denied)
+    const managedNames = new Set(Object.keys(managedServers))
+    for (const [name, client] of Array.from(clients.entries())) {
+      if (managedNames.has(name)) continue
+      clients.delete(name)
+      await client.close().catch(() => {})
+      status.set(name, { state: 'disabled by managed policy', tools: 0 })
+    }
+    await connectServers(managedServers, authUi)
+  }
+
+  /** The normal user + plugin + project scopes, when no managed-mcp.json is present.
+   * Connecting spawns processes and opens sockets, so it belongs here rather than in the
+   * factory: pi runs the factory for invocations that never start a session. Names still
+   * connected are filtered out, so a later session start only retries servers that failed
+   * or whose transport dropped, without duplicate-name warnings. */
+  async function connectNormalScopes(ctx: ExtensionContext, allowed: Set<string> | null, denied: Set<string>, authUi?: AuthUi): Promise<void> {
     // Plugin servers merge under the user scope (plugins are user-installed);
     // the user's own entry wins a name clash with a plugin's.
     const pluginServers = loadPluginServers(installedPlugins(os.homedir()))
-    const { allowed, denied } = mcpAllowDeny()
     const scoped = applyServerPolicy({ ...pluginServers, ...loadUserScope(os.homedir(), ctx.cwd) }, allowed, denied)
     // Claude's precedence is project over user for a duplicate name. A project .mcp.json
     // server only outranks the user's own when it will actually connect (the user already
@@ -1148,16 +1265,44 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     // entry cannot shadow a trusted user server by reusing its name. A gated project
     // server still awaiting the approval prompt does not preempt the user server: that is
     // a deliberate narrowing of Claude's rule to keep the safe default.
+    // The stored project decision, read without prompting: consent recorded inside
+    // the project only counts once the project itself has been approved.
     const projectPolicy = projectServerPolicy(ctx.cwd, os.homedir(), isProjectApprovedSilently(ctx))
-    const projectWinners = new Set(Object.keys(splitByPolicy(applyServerPolicy(loadConfigFrom(projectConfigPaths(ctx.cwd)), allowed, denied), projectPolicy).consented))
+    const { consented, gated } = splitByPolicy(applyServerPolicy(loadConfigFrom(projectConfigPaths(ctx.cwd)), allowed, denied), projectPolicy)
+    const projectWinners = new Set(Object.keys(consented))
     const userServers = Object.fromEntries(Object.entries(scoped).filter(([name]) => !clients.has(name) && !projectWinners.has(name)))
-    if (Object.keys(userServers).length > 0) await connectServers(userServers, authUiFor(ctx))
+    // The consented project servers carry no ordering dependency on the user scope:
+    // projectWinners already excludes their names from userServers, so the two batches
+    // are disjoint and connect concurrently, and startup pays the slower scope rather
+    // than the sum of both. Reconnect attempts after a refused confirm are safe:
+    // connectServers skips names that already connected.
+    const connects: Promise<void>[] = []
+    if (Object.keys(userServers).length > 0) connects.push(connectServers(userServers, authUi))
+    if (!projectConnected && Object.keys(consented).length > 0) connects.push(connectServers(consented, authUi))
+    await Promise.all(connects)
     // A project .mcp.json can run arbitrary commands on connect, so only honor it once
     // the project is trusted. Per-server settings refine that: disabled servers never
-    // connect, servers the user consented to individually connect without the
-    // whole-project confirm, and the rest stay behind it. Reconnect attempts after a
-    // refusal are safe: connectServers skips names that already connected.
-    if (!projectConnected) projectConnected = await connectProjectScope(ctx)
+    // connect, servers the user consented to individually connected above without the
+    // whole-project confirm, and the rest stay behind it, sequentially after both
+    // scopes so the confirm dialog never races a connect.
+    if (!projectConnected) projectConnected = await connectGatedProjectServers(ctx, gated, authUi)
+  }
+
+  pi.on('session_start', async (_event, ctx) => {
+    const authUi = authUiFor(ctx)
+    // The managed allow/deny lists filter every scope, including a managed-mcp.json set.
+    const { allowed, denied } = mcpAllowDeny()
+    // managed-mcp.json (beside managed-settings.json) takes exclusive control when present:
+    // only its servers load, and the user, project, and plugin scopes plus the whole
+    // project-approval flow below are skipped. An empty map disables MCP entirely. An absent
+    // file leaves the normal scopes untouched; a present but corrupt file fails closed to an
+    // empty set (see loadManagedMcpServers).
+    const managed = loadManagedMcpServers()
+    if (managed !== null) {
+      await connectManagedExclusive(managed, allowed, denied, authUi)
+    } else {
+      await connectNormalScopes(ctx, allowed, denied, authUi)
+    }
 
     pi.events.emit(MCP_TOOLS_CHANNEL, [...aliases])
 

package/extensions/memory.ts

@@ -14,11 +14,12 @@ import * as path from 'node:path'
 import { StringEnum } from '@earendil-works/pi-ai'
 import { type ExtensionAPI, withFileMutationQueue } from '@earendil-works/pi-coding-agent'
 import { Type } from 'typebox'
+import { claudeConfigDir } from './internal/config-dir.js'
 import { capForContext } from './internal/output-guard.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { findNearestFile, repoRoot } from './internal/project-root.js'
 
-const INDEX_FILE = 'MEMORY.md'
+export const INDEX_FILE = 'MEMORY.md'
 
 /** Claude loads the first 200 lines or 25KB of the memory index at startup. */
 export const INDEX_MAX_LINES = 200
@@ -282,7 +283,7 @@ function writeIndex(indexPath: string, content: string): void {
  * approved, since a project's `autoMemoryDirectory` is honored under the same trust
  * rule as hooks in settings files. Later files win. */
 export function memorySettingsFiles(cwd: string, home: string, approved: boolean): string[] {
-  const files = [path.join(home, '.claude', 'settings.json')]
+  const files = [path.join(claudeConfigDir(home), 'settings.json')]
   if (!approved) return files
   for (const name of ['settings.json', 'settings.local.json']) {
     files.push(findNearestFile(cwd, path.join('.claude', name)) ?? path.join(cwd, '.claude', name))
@@ -306,10 +307,65 @@ export function readMemorySettings(files: string[]): { autoMemoryEnabled?: unkno
   return merged
 }
 
+/** Write `autoMemoryEnabled` into the user settings file, preserving every other key
+ * and creating the file and its config directory when absent. Claude's /memory toggle
+ * writes to the user scope (relocated by CLAUDE_CONFIG_DIR); the value takes effect from
+ * the next session start, which is where autoMemoryEnabled is read.
+ *
+ * An absent file starts from an empty object so the toggle still lands. A file that is
+ * PRESENT but unparseable is refused, not overwritten: clobbering it would destroy the
+ * user's hooks, env and permissions config. The caller surfaces the returned failure. */
+export function setAutoMemoryEnabledSetting(home: string, value: boolean): { ok: true } | { ok: false; error: string } {
+  const dir = claudeConfigDir(home)
+  const file = path.join(dir, 'settings.json')
+  let current: Record<string, unknown> = {}
+  let raw: string | undefined
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    // Only a missing file means start fresh; any other read failure propagates.
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+  }
+  if (raw !== undefined) {
+    try {
+      const parsed = JSON.parse(raw)
+      if (parsed !== null && typeof parsed === 'object') current = parsed as Record<string, unknown>
+    } catch {
+      // Present but unparseable: refuse rather than overwrite the user's config.
+      return { ok: false, error: 'settings.json is not valid JSON; not modified' }
+    }
+  }
+  current.autoMemoryEnabled = value
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(file, `${JSON.stringify(current, null, 2)}\n`)
+  return { ok: true }
+}
+
 export default function memoryExtension(pi: ExtensionAPI) {
   let dir = memoryDir(process.cwd())
   let enabled = true
 
+  // The index is injected every turn but changes only through the tool or an external
+  // edit, so a turn costs one stat instead of a full read. The stat token (mtime plus
+  // size) catches external edits; save and delete drop the cache outright, since a
+  // rename landing within one mtime tick at the same size would slip past the token.
+  let indexCache: { token: string; index: string } | null = null
+
+  const indexStatToken = (): string => {
+    try {
+      const stat = fs.statSync(path.join(dir, INDEX_FILE))
+      return `${stat.mtimeMs}:${stat.size}`
+    } catch {
+      return 'missing'
+    }
+  }
+
+  const readIndexCached = (): string => {
+    const token = indexStatToken()
+    if (indexCache?.token !== token) indexCache = { token, index: readIndexQuietly(dir) }
+    return indexCache.index
+  }
+
   // These extensions also load inside spawned subagent processes, which carry the
   // PI_CODE_SUBAGENT marker. Claude does not load the main conversation's auto memory
   // into subagents (they get their own store through the agent `memory:` field), so
@@ -325,6 +381,7 @@ export default function memoryExtension(pi: ExtensionAPI) {
     enabled = autoMemoryEnabled(settings.autoMemoryEnabled, process.env)
     const override = typeof settings.autoMemoryDirectory === 'string' ? settings.autoMemoryDirectory : undefined
     dir = enabled ? resolveMemoryDir(ctx.cwd, override) : memoryDir(ctx.cwd)
+    indexCache = null
     if (!enabled) return
     const count = readIndexQuietly(dir)
       .split('\n')
@@ -334,7 +391,7 @@ export default function memoryExtension(pi: ExtensionAPI) {
 
   pi.on('before_agent_start', async (event) => {
     if (inSubagent() || !enabled) return
-    const index = readIndexQuietly(dir)
+    const index = readIndexCached()
     if (!index.trim()) return
     return {
       systemPrompt: `${event.systemPrompt}\n\n## Memory\n\nPersistent memories from earlier sessions (index):\n\n${capIndexForPrompt(index)}\nUse the memory tool with action "read" to load a memory's full content when relevant.`,
@@ -362,6 +419,8 @@ export default function memoryExtension(pi: ExtensionAPI) {
           return await saveMemory(dir, indexPath, name, params.description, params.content)
         } catch (error) {
           return { content: [{ type: 'text' as const, text: `Memory save failed: ${error instanceof Error ? error.message : String(error)}. The index was left untouched.` }], details: {} }
+        } finally {
+          indexCache = null
         }
       }
 
@@ -372,11 +431,66 @@ export default function memoryExtension(pi: ExtensionAPI) {
 
       if (params.action === 'delete') {
         if (!name) return { content: [{ type: 'text' as const, text: 'delete requires name.' }], details: {} }
-        return deleteMemory(dir, indexPath, name)
+        // In a finally like the save path: a delete that throws mid-write must still
+        // drop the cache, or the next turn injects a stale index.
+        try {
+          return await deleteMemory(dir, indexPath, name)
+        } finally {
+          indexCache = null
+        }
       }
 
       const index = readIndexQuietly(dir)
       return { content: [{ type: 'text' as const, text: index.trim() || 'No memories saved for this project yet.' }], details: {} }
     },
   })
+
+  // Claude's /memory lists the memory locations and toggles auto memory. pi has no
+  // editor seam, so the paths are printed rather than opened. The listing reads the
+  // settings chain live so it reflects a toggle written in the same session.
+  pi.registerCommand('memory', {
+    description: 'Show memory file locations and toggle auto memory (/memory [on|off])',
+    handler: async (args, ctx) => {
+      const home = os.homedir()
+      const arg = args.trim().toLowerCase()
+
+      if (arg === 'on' || arg === 'off') {
+        const next = arg === 'on'
+        let result: { ok: true } | { ok: false; error: string }
+        try {
+          result = setAutoMemoryEnabledSetting(home, next)
+        } catch (error) {
+          ctx.ui.notify(`Could not update auto memory: ${error instanceof Error ? error.message : String(error)}`, 'error')
+          return
+        }
+        if (!result.ok) {
+          ctx.ui.notify(result.error, 'error')
+          return
+        }
+        ctx.ui.notify(`Auto memory ${next ? 'enabled' : 'disabled'} in ${path.join(claudeConfigDir(home), 'settings.json')} (applies next session).`, 'info')
+        return
+      }
+
+      if (arg.length > 0) {
+        ctx.ui.notify('Usage: /memory [on|off]', 'error')
+        return
+      }
+
+      const approved = isProjectApprovedSilently(ctx)
+      const settings = readMemorySettings(memorySettingsFiles(ctx.cwd, home, approved))
+      const isEnabled = autoMemoryEnabled(settings.autoMemoryEnabled, process.env)
+      const override = typeof settings.autoMemoryDirectory === 'string' ? settings.autoMemoryDirectory : undefined
+      const store = resolveMemoryDir(ctx.cwd, override)
+      const lines = [
+        'Memory',
+        `  Auto memory: ${isEnabled ? 'on' : 'off'}`,
+        `  Store:       ${store}`,
+        `  Index:       ${path.join(store, INDEX_FILE)}`,
+        `  User memory (CLAUDE.md):    ${path.join(home, '.claude', 'CLAUDE.md')}`,
+        `  Project memory (CLAUDE.md): ${path.join(ctx.cwd, 'CLAUDE.md')}`,
+        'Toggle with /memory on or /memory off.',
+      ]
+      ctx.ui.notify(lines.join('\n'), 'info')
+    },
+  })
 }

package/extensions/notify.ts

@@ -21,6 +21,8 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
+import { claudeConfigDir } from './internal/config-dir.js'
+
 /** How a finished turn is announced, from Claude's `preferredNotifChannel`. */
 export type NotifChannel = 'desktop' | 'bell' | 'both' | 'off'
 
@@ -55,7 +57,7 @@ export function isAway(lastInputAt: number | undefined, now: number, thresholdMs
  * or change your notifications. */
 function readPreferredNotifChannel(home: string): unknown {
   try {
-    const settings = JSON.parse(fs.readFileSync(path.join(home, '.claude', 'settings.json'), 'utf-8'))
+    const settings = JSON.parse(fs.readFileSync(path.join(claudeConfigDir(home), 'settings.json'), 'utf-8'))
     return settings?.preferredNotifChannel
   } catch {
     return undefined

package/extensions/output-styles.ts

@@ -24,6 +24,7 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
+import { claudeConfigDir } from './internal/config-dir.js'
 import { installedPlugins } from './internal/plugins.js'
 import { isProjectApproved } from './internal/project-approval.js'
 import { findNearestDir, findNearestFile } from './internal/project-root.js'
@@ -82,7 +83,7 @@ function isDirectory(target: string): boolean {
  * verbatim into the system prompt.
  */
 export function styleDirs(cwd: string, home: string, trusted: boolean): string[] {
-  const dirs = [path.join(home, '.claude', 'output-styles')]
+  const dirs = [path.join(claudeConfigDir(home), 'output-styles')]
   if (trusted) dirs.push(findNearestDir(cwd, path.join('.claude', 'output-styles')) ?? path.join(cwd, '.claude', 'output-styles'))
   return dirs.filter((dir) => isDirectory(dir))
 }
@@ -129,7 +130,7 @@ export function loadStyles(dirs: string[]): OutputStyle[] {
 /** Settings files that carry `outputStyle`. Project settings apply only when trusted,
  * each the nearest of its name at or above cwd, as the hooks settings chain reads. */
 export function settingsFiles(cwd: string, home: string, trusted: boolean): string[] {
-  const files = [path.join(home, '.claude', 'settings.json')]
+  const files = [path.join(claudeConfigDir(home), 'settings.json')]
   if (!trusted) return files
   for (const name of ['settings.json', 'settings.local.json']) {
     files.push(findNearestFile(cwd, path.join('.claude', name)) ?? path.join(cwd, '.claude', name))

package/extensions/skills.ts

@@ -15,6 +15,7 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
+import { claudeConfigDir } from './internal/config-dir.js'
 import { installedPlugins } from './internal/plugins.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { findNearestDir } from './internal/project-root.js'
@@ -33,7 +34,7 @@ function isDirectory(target: string): boolean {
  * 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. */
 export function skillDirs(cwd: string, home: string, trusted: boolean): string[] {
-  const candidates = [path.join(home, '.claude', 'skills')]
+  const candidates = [path.join(claudeConfigDir(home), 'skills')]
   // Enabled plugins contribute their skills directories. pi's loader names a
   // skill by its directory, so a plugin skill registers without Claude's
   // /plugin: prefix; a rename-free approximation, disclosed in the README.