pi-code 1.0.9 → 1.0.11

package/extensions/hooks.ts

@@ -3,7 +3,14 @@
  *
  * Runs Claude Code's `.claude/settings.json` hooks on pi's lifecycle events, so
  * a project's existing hooks work under pi:
- * - PreToolUse      -> pi `tool_call` (can block the tool or rewrite its input)
+ * - PreToolUse      -> pi `tool_call` (can block the tool or rewrite its input), plus
+ *                      pi `user_bash` for a `!`/`!!` command the user runs directly (the
+ *                      model never issues these, so a deny-list guard would otherwise miss
+ *                      them). No pi tool call exists there, so the payload reports the
+ *                      Claude name "Bash"; a deny hands pi a synthetic failed result so
+ *                      the command never runs. UserBashEvent carries no execution result
+ *                      and fires only before the command runs, so it has no PostToolUse
+ *                      counterpart (pi never delivers the output to observe).
  * - PostToolUse     -> pi `tool_result` (block reasons and additionalContext are
  *                      appended next to the tool result, as Claude documents)
  * - SessionStart    -> pi `session_start` (stdout/additionalContext is injected as
@@ -62,6 +69,7 @@ import * as path from 'node:path'
 import type { Api, Model } from '@earendil-works/pi-ai'
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { runAgent } from './internal/agent-run.js'
+import { claudeConfigDir } from './internal/config-dir.js'
 import { INSTRUCTIONS_CHANNEL, isInstructionLoadEvent } from './internal/instruction-events.js'
 import { readManagedSettings } from './internal/managed-settings.js'
 import { isMcpToolAliases, MCP_TOOLS_CHANNEL } from './internal/mcp-alias.js'
@@ -83,6 +91,9 @@ const DEFAULT_TIMEOUT_S = 60
 interface HookCommand {
   type?: string
   command: string
+  /** exec-form: spawn `command` directly with these args and no shell (shell-form when
+   * absent). $ARGUMENTS in each arg is replaced with the event JSON. */
+  args?: string[]
   timeout?: number
   /** http entries: the endpoint POSTed to; `command` mirrors it for dedup and display. */
   url?: string
@@ -122,14 +133,15 @@ export interface HookRunResult {
 }
 /** 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. */
-export type HookCommandRunner = (command: string, payload: unknown, timeoutMs: number, projectDir?: string) => 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. */
+export type HookCommandRunner = (command: string, payload: unknown, timeoutMs: number, projectDir?: string, args?: string[]) => Promise<HookRunResult>
 
 /** Settings files to read, newest-winning. Project files load only when trusted, each
  * the nearest of its name at or above cwd (bounded at the repository root, matching
  * the approval walk), so a subdirectory session reads the settings that gated it. */
 export function hookFiles(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))
@@ -472,14 +484,23 @@ function killTree(child: ChildProcess): void {
   child.kill('SIGKILL')
 }
 
-export const runHookCommand: HookCommandRunner = (command, payload, timeoutMs, projectDir) =>
+export const runHookCommand: HookCommandRunner = (command, payload, timeoutMs, projectDir, args) =>
   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.
-    const env = projectDir ? { ...process.env, CLAUDE_PROJECT_DIR: projectDir } : process.env
-    const child = spawn('/bin/sh', ['-c', command], { stdio: ['pipe', 'pipe', 'pipe'], detached: true, env })
+    // 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 })
     let stdout = ''
     let stderr = ''
     let settled = false
@@ -673,6 +694,18 @@ export function lastAssistantText(messages: ReadonlyArray<{ role: string; conten
   return ''
 }
 
+/** Claude overrides a Stop hook after it blocks this many times in a row with no user
+ * progress, ending the turn with a warning rather than looping forever. */
+const DEFAULT_STOP_HOOK_BLOCK_CAP = 8
+
+/** The consecutive-block cap for the Stop hook: CLAUDE_CODE_STOP_HOOK_BLOCK_CAP when it
+ * is a positive integer, else the default. A non-positive or malformed value falls back
+ * to the default rather than capping at zero (which would suppress the very first block). */
+export function stopHookBlockCap(env: Record<string, string | undefined> = process.env): number {
+  const override = Number.parseInt(env.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP ?? '', 10)
+  return Number.isInteger(override) && override > 0 ? override : DEFAULT_STOP_HOOK_BLOCK_CAP
+}
+
 /** Above 2^31-1 ms Node clamps a timer to 1ms, which would kill the hook instantly. */
 const MAX_TIMEOUT_S = 2_147_483
 
@@ -833,6 +866,9 @@ export default function hooksExtension(pi: ExtensionAPI) {
   let allowedHttpHookUrls: string[] | undefined
   let pendingSessionContext: string[] = []
   let stopHookActive = false
+  /** Consecutive Stop-hook blocks with no user progress between them. Reset on user input
+   * and on a non-blocking Stop; at the cap the continuation is suppressed and the turn ends. */
+  let stopHookBlockCount = 0
   let sessionCtx: ExtensionContext | undefined
   /** Claude's disableAllHooks escape hatch was set somewhere in the honored chain. */
   let hooksDisabled = false
@@ -856,7 +892,7 @@ export default function hooksExtension(pi: ExtensionAPI) {
       if (hook.type === 'prompt') return runPromptHook(hook, merged, ctx.model, ms)
       if (hook.type === 'agent') return runAgentHook(hook, merged, ms, (ctx.model as { id?: string } | undefined)?.id)
       if (hook.type === 'mcp_tool') return runMcpToolHook(hook, merged, ms)
-      return runHookCommand(hook.command, merged, ms, projectDir)
+      return runHookCommand(hook.command, merged, ms, projectDir, hook.args)
     }
   // Claude matchers name MCP tools mcp__<server>__<tool>; pi-code registers them as
   // <server>_<tool>. The mcp extension publishes the mapping on pi's shared bus.
@@ -992,10 +1028,38 @@ export default function hooksExtension(pi: ExtensionAPI) {
     return { content: [...event.content, ...feedback.map((text) => ({ type: 'text' as const, text }))] }
   })
 
+  // Claude's PreToolUse for Bash, extended to a command the user runs directly with the
+  // `!`/`!!` prefix. pi fires user_bash before executing it, and the model never sees it,
+  // so without this a guard that blocks `git push -f` from the model would not stop the
+  // same command typed by hand. There is no pi tool call, so the matcher sees both pi's
+  // "bash" and the Claude name "Bash" (exactly as an MCP alias is bridged) and the payload
+  // reports "Bash", the tool_name a Claude-written PreToolUse Bash hook expects. The
+  // payload carries no tool_use_id (no model tool call produced it). UserBashEventResult
+  // exposes no block flag: a deny is enforced through `result` ("extension handled
+  // execution, use this result"), a synthetic failed BashResult that stands in for the
+  // command so it never runs and its deny reason shows as the output. The event delivers
+  // no execution result and fires only before the command runs, so there is deliberately
+  // no PostToolUse for it.
+  pi.on('user_bash', async (event, ctx) => {
+    const decision = await runPreToolUse(config, 'bash', { command: event.command }, boundRunner(ctx), 'Bash', (message) => ctx.ui.notify(message, 'warning'))
+    if (!decision.block) return undefined
+    // Claude's "ask": prompt before running and let the command through on approval; with
+    // no UI (headless) the block stands, the same safe default as the tool_call path.
+    if (decision.ask && ctx.hasUI) {
+      const approved = await ctx.ui.confirm('Allow this command?', decision.reason ?? 'A hook asks you to confirm this command.')
+      if (approved) return undefined
+    }
+    const reason = decision.reason ?? 'Command blocked by hook'
+    return { result: { output: `Blocked by hook: ${reason}`, exitCode: 1, cancelled: false, truncated: false } }
+  })
+
   pi.on('input', async (event, ctx) => {
     // Only genuine user input; extension-injected messages (plan-mode, subagent) are not
     // prompts the user submitted.
     if (event.source === 'extension') return { action: 'continue' }
+    // Genuine user input is progress, so it breaks a Stop-hook continuation streak: the
+    // block cap counts only consecutive blocks with nothing from the user in between.
+    stopHookBlockCount = 0
     const decision = await runUserPromptSubmit(config, event.text, boundRunner(ctx), (message) => ctx.ui.notify(message, 'warning'))
     if (decision.block) {
       // pi's input result has no reason channel, so surface why before consuming it.
@@ -1048,8 +1112,25 @@ export default function hooksExtension(pi: ExtensionAPI) {
         return { block: false, reason: '' }
       })
       .find((verdict) => verdict.block)
-    stopHookActive = block !== undefined
-    if (block) pi.sendMessage({ customType: 'claude-stop-hook', content: block.reason, display: true }, { triggerTurn: true })
+    if (!block) {
+      // A non-blocking Stop breaks the streak: the next block starts a fresh count.
+      stopHookActive = false
+      stopHookBlockCount = 0
+      return
+    }
+    stopHookBlockCount += 1
+    const cap = stopHookBlockCap()
+    if (stopHookBlockCount >= cap) {
+      // Claude overrides a Stop hook that has blocked cap times in a row with no user
+      // progress: suppress the continuation, warn, and let the turn end so the loop cannot
+      // run forever. Reset the count so a later run (or user turn) starts clean.
+      stopHookActive = false
+      stopHookBlockCount = 0
+      ctx.ui.notify(`Stop hook block cap reached (${cap} consecutive blocks); ending the turn.`, 'warning')
+      return
+    }
+    stopHookActive = true
+    pi.sendMessage({ customType: 'claude-stop-hook', content: block.reason, display: true }, { triggerTurn: true })
   })
 
   pi.on('session_before_compact', async (event, ctx) => {

package/extensions/internal/command-file.ts

@@ -35,7 +35,16 @@ export interface ParsedCommand {
    * command's injected spans run (see spanExec). */
   shell?: string
   model?: string
+  /** `effort:` per-command thinking-level override, one of pi's ThinkingLevel values
+   * (off/minimal/low/medium/high/xhigh/max); undefined when absent or unrecognized. */
+  effort?: string
+  /** `when_to_use:` extra trigger text appended to the slash_command tool listing only,
+   * never to the user-facing command description. */
+  whenToUse?: string
   disableModelInvocation: boolean
+  /** `user-invocable:` false hides the command from the slash-command surface while
+   * keeping it callable by the model through the slash_command tool. Default true. */
+  userInvocable: boolean
   body: string
 }
 
@@ -236,6 +245,15 @@ const text = (value: unknown): string => {
 const YAML_TRUE = new Set(['true', 'yes', 'on', 'y', '1'])
 const isFlagEnabled = (value: unknown): boolean => value === true || YAML_TRUE.has(text(value).toLowerCase())
 
+/** YAML's negative boolean spellings, the mirror of YAML_TRUE. A flag that defaults to
+ * true (user-invocable) is turned off only by one of these; any other value, absent
+ * included, leaves it on, so an unrelated string never silently hides a command. */
+const YAML_FALSE = new Set(['false', 'no', 'off', 'n', '0'])
+const isFlagDisabled = (value: unknown): boolean => value === false || YAML_FALSE.has(text(value).toLowerCase())
+
+/** pi's ThinkingLevel union, the values a command's `effort:` override may name. */
+const THINKING_LEVELS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
+
 /** Claude writes `argument-hint: [pr]`, which YAML reads as a list; render it back. */
 const hint = (value: unknown): string => (Array.isArray(value) ? `[${value.join(', ')}]` : text(value))
 
@@ -265,6 +283,7 @@ export function parseCommandFile(content: string): ParsedCommand {
   const disable = frontmatter['disable-model-invocation']
   const grants = parseToolGrants(frontmatter['allowed-tools'])
   const shell = text(frontmatter.shell).toLowerCase()
+  const effort = text(frontmatter.effort).toLowerCase()
   return {
     description: text(frontmatter.description) || firstLine.slice(0, 60),
     argumentHint: hint(frontmatter['argument-hint']) || undefined,
@@ -276,7 +295,11 @@ export function parseCommandFile(content: string): ParsedCommand {
     disallowedTools: parseToolGrants(frontmatter['disallowed-tools'])?.tools,
     shell: SHELLS.has(shell) ? shell : undefined,
     model: text(frontmatter.model) || undefined,
+    // An unrecognized effort is dropped rather than passed to setThinkingLevel.
+    effort: THINKING_LEVELS.has(effort) ? effort : undefined,
+    whenToUse: text(frontmatter.when_to_use) || undefined,
     disableModelInvocation: isFlagEnabled(disable),
+    userInvocable: !isFlagDisabled(frontmatter['user-invocable']),
     body,
   }
 }
@@ -453,7 +476,9 @@ export function spanExec(shell: string | undefined, projectDir: string, script:
   if (shell === 'powershell') {
     const binary = resolveBinary()
     if (binary !== undefined) {
-      const preamble = `$ErrorActionPreference='Continue'\n$env:CLAUDE_PROJECT_DIR='${powershellQuote(projectDir)}'`
+      // CLAUDECODE=1 marks every subprocess Claude spawns; pi.exec takes no env, so
+      // it is exported in the script alongside CLAUDE_PROJECT_DIR.
+      const preamble = `$ErrorActionPreference='Continue'\n$env:CLAUDE_PROJECT_DIR='${powershellQuote(projectDir)}'\n$env:CLAUDECODE='1'`
       // No in-script 2>&1: under pwsh 7 it does not merge a native command's
       // stderr on a script block, so mergeStreams has the caller append it. The
       // trailing exit forwards a failed native command's code, which pwsh
@@ -470,7 +495,7 @@ export function spanExec(shell: string | undefined, projectDir: string, script:
   // comment-only span is a hard sh syntax error (exit 2) that aborted the whole
   // invocation, and `:` keeps such a span the harmless no-op it was on HEAD
   // while the group still merges stderr for real spans.
-  return { command: '/bin/sh', args: ['-c', `export CLAUDE_PROJECT_DIR='${quoted}'\n{ :\n${script}\n} 2>&1`] }
+  return { command: '/bin/sh', args: ['-c', `export CLAUDE_PROJECT_DIR='${quoted}'\nexport CLAUDECODE=1\n{ :\n${script}\n} 2>&1`] }
 }
 
 interface FenceBlock {

package/extensions/internal/config-dir.ts

@@ -0,0 +1,24 @@
+/**
+ * CLAUDE_CONFIG_DIR: Claude Code's override for the home configuration directory.
+ *
+ * Claude relocates the entire ~/.claude configuration tree (settings.json, commands,
+ * agents, skills, plugins, output-styles, CLAUDE.md) when CLAUDE_CONFIG_DIR is set,
+ * so a user can keep that config outside their home directory. This resolves the
+ * home-scope config root for every consumer; a project's own `.claude/` directory is
+ * a separate scope and is never affected. A leading `~` expands against `home`, and
+ * the result is resolved to an absolute path so a relative value cannot depend on the
+ * reader's working directory.
+ */
+
+import * as path from 'node:path'
+
+/** The home-scope Claude config directory: CLAUDE_CONFIG_DIR (expanded, absolute)
+ * when set to a non-empty value, otherwise `<home>/.claude`. */
+export function claudeConfigDir(home: string): string {
+  const override = process.env.CLAUDE_CONFIG_DIR
+  if (override && override.trim().length > 0) {
+    const expanded = override.startsWith('~') ? path.join(home, override.slice(1)) : override
+    return path.resolve(expanded)
+  }
+  return path.join(home, '.claude')
+}

package/extensions/internal/plugins.ts

@@ -15,6 +15,8 @@
 import * as fs from 'node:fs'
 import * as path from 'node:path'
 
+import { claudeConfigDir } from './config-dir.js'
+
 export interface InstalledPlugin {
   name: string
   /** The version directory: ${CLAUDE_PLUGIN_ROOT}. */
@@ -148,8 +150,8 @@ function pluginFingerprint(cacheDir: string, settingsFiles: string[]): string {
  * because any settings edit or cache-tree change invalidates it.
  */
 export function installedPlugins(home: string, extraSettingsFiles: string[] = []): InstalledPlugin[] {
-  const cacheDir = path.join(home, '.claude', 'plugins', 'cache')
-  const settingsFiles = [path.join(home, '.claude', 'settings.json'), ...extraSettingsFiles]
+  const cacheDir = path.join(claudeConfigDir(home), 'plugins', 'cache')
+  const settingsFiles = [path.join(claudeConfigDir(home), 'settings.json'), ...extraSettingsFiles]
   const key = [home, ...extraSettingsFiles].join('\n')
   const fingerprint = pluginFingerprint(cacheDir, settingsFiles)
   const cached = pluginCache.get(key)
@@ -180,7 +182,7 @@ function resolvePlugin(home: string, cacheDir: string, marketplace: string, plug
   const name = typeof manifest.name === 'string' && manifest.name.length > 0 ? manifest.name : pluginDir
   const id = qualified.replace(/[^A-Za-z0-9]+/g, '-')
   const userConfig = configs[qualified] ?? configs[pluginDir] ?? configs[name]
-  return { name, root, dataDir: path.join(home, '.claude', 'plugins', 'data', id), manifest, ...(userConfig ? { userConfig } : {}) }
+  return { name, root, dataDir: path.join(claudeConfigDir(home), 'plugins', 'data', id), manifest, ...(userConfig ? { userConfig } : {}) }
 }
 
 /** The two plugin path variables, textually substituted into plugin-shipped

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. */
@@ -799,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)
@@ -809,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)
@@ -845,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)
@@ -883,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) {
@@ -940,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.
@@ -1027,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 }
@@ -1143,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
@@ -1165,7 +1271,6 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     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)))
-    const authUi = 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
@@ -1181,6 +1286,23 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     // 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])