pi-code 1.0.52 → 1.0.54

package/extensions/commands.ts

@@ -43,10 +43,10 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent'
 import { Type } from 'typebox'
-
 import { matchesBashRules } from './internal/bash-rules.js'
 import { type CommandExec, type DiscoveredCommand, discoverCommandFiles, expandDynamicContent, type ParsedCommand, type PathRuleTool, parseCommandFile, resolvePowershellBinary, spanExec, substituteArgsDetailed, substituteVars } from './internal/command-file.js'
 import { claudeConfigDir } from './internal/config-dir.js'
+import { claudeEffortLevel } from './internal/effort.js'
 import { managedSettingsFile, readManagedSettings } from './internal/managed-settings.js'
 import { capForContext } from './internal/output-guard.js'
 import { matchesPathRules } from './internal/path-rules.js'
@@ -174,10 +174,19 @@ export function shellExecutionDisabled(cwd: string, home: string, trusted: boole
   if (readManagedSettings().disableSkillShellExecution === true) return true
   const files = claudeSettingsChain(cwd, home, trusted)
   return files.some((file) => {
+    let raw: string
+    try {
+      raw = fs.readFileSync(file, 'utf-8')
+    } catch {
+      return false // no such file: genuinely not a policy statement
+    }
     try {
-      return (JSON.parse(fs.readFileSync(file, 'utf-8')) as Record<string, unknown>).disableSkillShellExecution === true
+      return (JSON.parse(raw) as Record<string, unknown>).disableSkillShellExecution === true
     } catch {
-      return false // missing or invalid file: not a policy statement
+      // Present but unreadable: the user may believe this file disables skill shells, so
+      // say so rather than silently leaving them enabled.
+      console.warn(`pi-code: ignoring ${file}: not valid JSON; skill shell execution stays as the other settings leave it`)
+      return false
     }
   })
 }
@@ -187,7 +196,9 @@ function commandVars(ctx: { cwd: string }, filePath: string, plugin?: CommandPlu
   const varCtx = ctx as unknown as VarContext
   return {
     CLAUDE_SESSION_ID: varCtx.sessionManager?.getSessionId?.(),
-    CLAUDE_EFFORT: varCtx.thinkingLevel,
+    // Claude vocabulary only, and unset when thinking is off: the variable promises
+    // low|medium|high|xhigh|max, and an unset one stays literal in the body.
+    CLAUDE_EFFORT: claudeEffortLevel(varCtx.thinkingLevel),
     CLAUDE_SKILL_DIR: path.dirname(filePath),
     CLAUDE_PROJECT_DIR: repoRoot(ctx.cwd) ?? ctx.cwd,
     CLAUDE_PLUGIN_ROOT: plugin?.root,

package/extensions/git-checkpoint.ts

@@ -18,6 +18,7 @@ import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { claudeConfigDir } from './internal/config-dir.js'
 
 const CUSTOM_TYPE = 'git-checkpoint'
 /** Sidecar inside the bare shadow repo recording the work tree it snapshots. */
@@ -37,6 +38,21 @@ interface Checkpoint {
  * for the life of the machine. */
 export const CHECKPOINT_RETENTION_DAYS = 30
 
+/** The retention period in effect: Claude keeps checkpoints for 30 days and says to
+ * "change the period with cleanupPeriodDays". Read from the user scope, which is where a
+ * setting about the user's own disk belongs; a non-positive or unreadable value keeps the
+ * default rather than sweeping everything away. */
+export function checkpointRetentionDays(home: string = os.homedir()): number {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(path.join(claudeConfigDir(home), 'settings.json'), 'utf-8'))
+    const declared = (parsed as { cleanupPeriodDays?: unknown }).cleanupPeriodDays
+    if (typeof declared === 'number' && Number.isFinite(declared) && declared > 0) return declared
+  } catch {
+    // No user settings, or unreadable: the default period stands.
+  }
+  return CHECKPOINT_RETENTION_DAYS
+}
+
 /** Claude keeps the 100 most recent checkpoints per session. Older ones drop off the
  * rewind list; their commits stay in the shadow repo until the retention sweep. */
 export const MAX_CHECKPOINTS_PER_SESSION = 100
@@ -179,7 +195,7 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
       shadowDir = path.join(checkpointsRoot, `${sessionSlug(sessionFile)}-${cwdSlug(ctx.cwd)}`)
       ctx.ui.notify(`Checkpoints for this session were recorded in ${recorded}; starting fresh checkpoints for ${ctx.cwd} (earlier ones are not restorable here)`, 'warning')
     }
-    pruneCheckpointRepos(checkpointsRoot, CHECKPOINT_RETENTION_DAYS, shadowDir)
+    pruneCheckpointRepos(checkpointsRoot, checkpointRetentionDays(os.homedir()), shadowDir)
     const check = await pi.exec('git', ['--git-dir', shadowDir, 'rev-parse', '--git-dir'], { cwd: ctx.cwd })
     if (check.code !== 0) {
       const init = await pi.exec('git', ['init', '--bare', '-b', 'main', shadowDir], { cwd: ctx.cwd })
@@ -194,7 +210,7 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
     }
     // Written on every start, so repos that predate the sidecar pick it up too.
     rememberWorkTree(shadowDir, ctx.cwd)
-    await mirrorLocalExcludes(ctx.cwd)
+    await mirrorLocalExcludes(ctx)
   }
 
   /** git reads ignore rules from the tree's .gitignore files, the user's global excludes,
@@ -203,7 +219,8 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
    * would be snapshotted and restored. Mirror it into the shadow on every start; the
    * global excludes stay untouched (core.excludesFile is single-valued, so pointing it
    * at the repo file would replace them). */
-  async function mirrorLocalExcludes(cwd: string): Promise<void> {
+  async function mirrorLocalExcludes(ctx: ExtensionContext): Promise<void> {
+    const cwd = ctx.cwd
     if (!shadowDir) return
     // Resolved through git so a linked worktree maps to its common dir; outside a repo
     // git exits 128 and there is nothing to mirror.
@@ -217,8 +234,10 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
       } else {
         fs.rmSync(target, { force: true })
       }
-    } catch {
-      // A failed mirror only means local excludes are not honored this session.
+    } catch (error) {
+      // Without the mirror, files the user excluded locally are snapshotted into the
+      // checkpoint store and restored by /rewind, so this is not a silent fallback.
+      ctx.ui.notify(`Checkpoints cannot honor this repository's .git/info/exclude: ${error instanceof Error ? error.message : String(error)}`, 'warning')
     }
   }
 

package/extensions/hooks/decisions.ts

@@ -262,8 +262,6 @@ export interface PromptDecision {
   block: boolean
   reason?: string
   context: string
-  /** Claude's suppressOriginalPrompt: the hook's context replaces the prompt. */
-  suppress?: boolean
 }
 
 /** Additional context a UserPromptSubmit hook contributes: an explicit
@@ -291,17 +289,13 @@ export async function runUserPromptSubmit(config: HooksConfig, prompt: string, r
   }
   if (onSystemMessage) surfaceSystemMessages(results, onSystemMessage)
   const contexts: string[] = []
-  let suppress = false
   for (const result of results) {
     const decision = interpretHookResult(result.code, result.stdout, result.stderr)
     if (decision.block) return { block: true, reason: decision.reason, context: '' }
-    // Claude's suppressOriginalPrompt: any hook setting it hides the original
-    // prompt, and the collected context is what reaches the model.
-    if (tryParseJson(result.stdout)?.hookSpecificOutput?.suppressOriginalPrompt === true) suppress = true
     const context = promptContext(result.stdout)
     if (context) contexts.push(context)
   }
-  return { block: false, context: contexts.join('\n'), suppress }
+  return { block: false, context: contexts.join('\n') }
 }
 
 /** The feedback lines one PostToolUse/PostToolUseFailure result appends next to the

package/extensions/hooks/index.ts

@@ -96,6 +96,7 @@
 
 import * as os from 'node:os'
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { claudeEffortLevel } from '../internal/effort.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'
@@ -186,6 +187,25 @@ const IDLE_PROMPT_DELAY_MS = 60_000
  * Claude Code restores on resume. */
 const MODEL_SELECT_SOURCE: Record<string, string> = { set: 'command', cycle: 'picker', restore: 'resume' }
 
+/** One Stop hook result read as a verdict. Claude: `continue` "takes precedence over any
+ * event-specific decision fields", and stopReason is the message shown when it is false,
+ * so a hook asking to stop wins over its own block whatever exit code carried it. Any
+ * blocking spelling counts, including the prompt and agent hook reply schemas, and a
+ * non-error additionalContext feeds back the same way so the block cap still bounds it. */
+function stopVerdict(result: HookRunResult, stopMessages: string[]): { block: boolean; reason: string } {
+  const parsed = tryParseJson(result.stdout)
+  if (parsed?.continue === false) {
+    if (parsed.stopReason) stopMessages.push(String(parsed.stopReason))
+    return { block: false, reason: '' }
+  }
+  if (result.code === 2) return { block: true, reason: jsonBlockVerdict(parsed, 'Stop blocked by hook')?.reason ?? (result.stderr.trim() || 'Stop blocked by hook') }
+  const verdict = jsonBlockVerdict(parsed, 'Stop blocked by hook')
+  if (verdict) return { block: true, reason: verdict.reason }
+  const context = parsed?.hookSpecificOutput?.additionalContext
+  if (typeof context === 'string' && context.length > 0) return { block: true, reason: context }
+  return { block: false, reason: '' }
+}
+
 export default function hooksExtension(pi: ExtensionAPI) {
   let config: HooksConfig = {}
   let projectDir = ''
@@ -228,7 +248,9 @@ export default function hooksExtension(pi: ExtensionAPI) {
     const common: Record<string, unknown> = { session_id: ctx.sessionManager.getSessionId(), cwd: ctx.cwd, permission_mode: permissionMode }
     const transcript = ctx.sessionManager.getSessionFile()
     if (transcript) common.transcript_path = transcript
-    if (ctx.thinkingLevel) common.effort = { level: ctx.thinkingLevel }
+    // Claude vocabulary only: pi's minimal maps to low and off carries no effort.
+    const effort = claudeEffortLevel(ctx.thinkingLevel)
+    if (effort) common.effort = { level: effort }
     return common
   }
   /** Claude's prompt-hook `model` override, resolved against the models this user
@@ -512,7 +534,11 @@ export default function hooksExtension(pi: ExtensionAPI) {
     const response = (alias === undefined && !event.isError ? claudeToolResponse(event.toolName, event.input, textContent(event.content), event.isError, ctx.cwd) : undefined) ?? { content: event.content, details: event.details, isError: event.isError }
     const startedAt = toolStartTimes.get(event.toolCallId)
     toolStartTimes.delete(event.toolCallId)
-    const payload = { hook_event_name: eventName, tool_name: translatedName ?? event.toolName, tool_input: translatedInput ?? event.input, tool_response: response, ...(startedAt === undefined ? {} : { duration_ms: Date.now() - startedAt }) }
+    // Claude delivers a failure as top-level fields rather than a tool_response: "error
+    // information as top-level fields ... error ... is_interrupt". is_interrupt is false
+    // here because pi reports a cancelled tool through the result, not this event.
+    const failure = event.isError ? { error: textContent(event.content), is_interrupt: false } : { tool_response: response }
+    const payload = { hook_event_name: eventName, tool_name: translatedName ?? event.toolName, tool_input: translatedInput ?? event.input, ...failure, ...(startedAt === undefined ? {} : { duration_ms: Date.now() - startedAt }) }
     const run = boundRunner(ctx, { tool_use_id: event.toolCallId })
     const results = await Promise.all(commands.map((command) => run(command, payload, timeoutMs(command))))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
@@ -576,10 +602,11 @@ export default function hooksExtension(pi: ExtensionAPI) {
       return { action: 'handled' }
     }
     // Claude injects a UserPromptSubmit hook's context ahead of the prompt; transform is
-    // pi's seam for rewriting the submitted text. With suppressOriginalPrompt the
-    // context replaces the prompt entirely (honored only when context exists, since
-    // an empty submission would be no turn at all).
-    if (decision.context) return { action: 'transform', text: decision.suppress ? decision.context : `${decision.context}\n\n${event.text}` }
+    // pi's seam for rewriting the submitted text. The prompt itself always survives:
+    // "UserPromptSubmit: can't replace the prompt; it only injects additionalContext
+    // alongside it". suppressOriginalPrompt scopes to the block message, which never
+    // carries the prompt here, so it needs nothing of its own.
+    if (decision.context) return { action: 'transform', text: `${decision.context}\n\n${event.text}` }
     return { action: 'continue' }
   })
 
@@ -593,12 +620,11 @@ export default function hooksExtension(pi: ExtensionAPI) {
   // handler on a UI dialog, which would starve the Stop hook and idle notification
   // until the user answers it. agent_end can fire slightly early before a rare
   // automatic retry or compaction; that is the better tradeoff.
-  pi.on('agent_end', async (event, ctx) => {
-    // Claude's Notification event, for the one type pi can honestly source: the
-    // agent finished and is waiting for input. Per Claude, idle_prompt fires when
-    // the turn ended about 60 seconds ago and the user hasn't typed since, so it
-    // arms here and input or the next turn cancels it. Observational only; exit
-    // codes and JSON output are ignored, as Claude documents for this event.
+  /** Claude's Notification event, for the one type pi can honestly source: the agent
+   * finished and is waiting for input. idle_prompt fires when the turn ended about 60
+   * seconds ago and the user has not typed since, so it arms here and input or the next
+   * turn cancels it. Observational only; exit codes and JSON output are ignored. */
+  const armIdlePrompt = (ctx: ExtensionContext): void => {
     cancelIdlePrompt()
     const notifyCommands = matchingCommands(config.Notification, ['idle_prompt'])
     if (notifyCommands.length > 0) {
@@ -608,6 +634,9 @@ export default function hooksExtension(pi: ExtensionAPI) {
       }, IDLE_PROMPT_DELAY_MS)
       idlePromptTimer.unref?.()
     }
+  }
+  pi.on('agent_end', async (event, ctx) => {
+    armIdlePrompt(ctx)
 
     // In a subagent child, the agent-frontmatter Stop hooks were converted to
     // SubagentStop and fire here, at the child's own end, notify-style; before the
@@ -643,24 +672,12 @@ export default function hooksExtension(pi: ExtensionAPI) {
     const run = boundRunner(ctx)
     const results = await Promise.all(commands.map((command) => run(command, payload, timeoutMs(command))))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
+    const stopMessages: string[] = []
     const block = results
       .filter((result) => !result.timedOut)
-      .map((result) => {
-        const parsed = tryParseJson(result.stdout)
-        if (result.code === 2) return { block: true, reason: jsonBlockVerdict(parsed, 'Stop blocked by hook')?.reason ?? (result.stderr.trim() || 'Stop blocked by hook') }
-        // Any JSON blocking spelling counts, including the prompt/agent hook reply
-        // schemas (permissionDecision deny, ok:false), which arrive as stdout here.
-        const verdict = jsonBlockVerdict(parsed, 'Stop blocked by hook')
-        if (verdict) return { block: true, reason: verdict.reason }
-        // Claude's non-error continue: additionalContext feeds back and the
-        // conversation continues so Claude can act on it. It rides the same
-        // continuation path (and the same block cap) so a hook emitting it every
-        // firing cannot loop the turn forever.
-        const context = parsed?.hookSpecificOutput?.additionalContext
-        if (typeof context === 'string' && context.length > 0) return { block: true, reason: context }
-        return { block: false, reason: '' }
-      })
+      .map((result) => stopVerdict(result, stopMessages))
       .find((verdict) => verdict.block)
+    for (const message of stopMessages) ctx.ui.notify(message, 'warning')
     if (!block) {
       // A non-blocking Stop breaks the streak: the next block starts a fresh count.
       stopHookActive = false
@@ -689,6 +706,17 @@ export default function hooksExtension(pi: ExtensionAPI) {
     const payload = { hook_event_name: 'PreCompact', trigger: trigger.value, custom_instructions: event.customInstructions ?? '' }
     const results = await runNotifyHooks(matchingCommands(config.PreCompact, trigger.names), payload, boundRunner(ctx))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
+    // Claude: "Exit with code 2 to block compaction. For a manual /compact, the stderr
+    // message is shown to the user. You can also block by returning JSON with
+    // `decision: block`." pi cancels through the result, and a blocked automatic
+    // compaction is worth a notice too: the context stays full either way.
+    for (const [index, result] of results.entries()) {
+      const parsed = tryParseJson(result.stdout)
+      const blocked = result.code === 2 && !result.timedOut ? { reason: result.stderr.trim() || 'Compaction blocked by hook' } : jsonBlockVerdict(parsed, 'Compaction blocked by hook')
+      if (!blocked) continue
+      ctx.ui.notify(`Compaction blocked by ${matchingCommands(config.PreCompact, trigger.names)[index]?.command ?? 'hook'}: ${blocked.reason}`, 'warning')
+      return { cancel: true }
+    }
   })
 
   pi.on('session_compact', async (event, ctx) => {

package/extensions/hooks/matcher.ts

@@ -4,7 +4,7 @@
  * commands an event fires. Owns the module-level compiled-matcher cache.
  */
 
-import { matchesBashRules } from '../internal/bash-rules.js'
+import { matchesBashIfFilter } from '../internal/bash-rules.js'
 import { matchesPathRules, type PathAnchors } from '../internal/path-rules.js'
 import type { HookCommand, HookMatcher } from './config.js'
 
@@ -159,14 +159,16 @@ export interface IfFilterTarget {
 
 /** Claude's `if` handler field: permission-rule syntax evaluated only on tool
  * events; on any other event a hook carrying `if` never runs. A bare tool name
- * matches by name; `Bash(pattern)` evaluates against the command via the shared
- * bash-rule matcher and file-tool patterns against the path via the shared
- * permission path rules. A pattern for any other tool matches nothing, which is
+ * matches by name; `Bash(pattern)` evaluates against the command through the if-filter
+ * matcher, which is best effort and errs toward running the hook, and file-tool patterns
+ * against the path via the shared permission path rules. A pattern for any other tool matches nothing, which is
  * also what an unparseable rule does. */
 export function passesIfFilter(hook: HookCommand, target: IfFilterTarget | undefined): boolean {
   if (hook.if === undefined) return true
   if (target === undefined) return false
-  const parsed = /^([A-Za-z_|]+?)(?:\((.*)\))?$/.exec(hook.if.trim())
+  // Digits and hyphens are part of a tool name: an MCP tool is mcp__<server>__<tool> and
+  // server names carry both, so a stricter class silently matched nothing.
+  const parsed = /^([\w|-]+?)(?:\((.*)\))?$/.exec(hook.if.trim())
   if (!parsed) return false
   const fold = (name: string): string => name.toLowerCase().replaceAll('-', '_')
   const ruleTools = new Set(parsed[1].split('|').map(fold))
@@ -177,7 +179,7 @@ export function passesIfFilter(hook: HookCommand, target: IfFilterTarget | undef
   const input = target.input as Record<string, unknown> | null
   if (fold(target.piName) === 'bash' || (target.claudeName !== undefined && fold(target.claudeName) === 'bash')) {
     const command = typeof input?.command === 'string' ? input.command : ''
-    return command.length > 0 && matchesBashRules(command, [pattern])
+    return command.length > 0 && matchesBashIfFilter(command, pattern)
   }
   let filePath = ''
   if (typeof input?.path === 'string') filePath = input.path

package/extensions/internal/bash-rules.ts

@@ -30,6 +30,50 @@ function matchesRule(segment: string, rule: string): boolean {
   return segment === normalized
 }
 
+/** Leading `VAR=value` assignments, which Claude strips before matching an `if` pattern. */
+const LEADING_ASSIGNMENTS = /^(?:[A-Za-z_]\w*=(?:"[^"]*"|'[^']*'|\S*)\s+)+/
+
+/** The bodies of `$(...)`, `` `...` ``, `<(...)` and `>(...)`, which run commands of their own. */
+function substitutionBodies(command: string): string[] {
+  const bodies: string[] = []
+  for (const match of command.matchAll(/\$\(([^()]*)\)|`([^`]*)`|[<>]\(([^()]*)\)/g)) {
+    const body = match[1] ?? match[2] ?? match[3]
+    if (body?.trim()) bodies.push(body.trim())
+  }
+  return bodies
+}
+
+/** Whether the first word of a segment is something only the shell can resolve. */
+const headUnresolvable = (segment: string): boolean => /[$`]/.test(segment.split(/\s+/, 1)[0] ?? '')
+
+/** Whether a pattern names more than the command itself, like `git push *` against `git *`. */
+const namesMoreThanCommand = (rule: string): boolean => rule.split('*', 1)[0].trim().includes(' ')
+
+/**
+ * Claude's `if` filter for a Bash call, which decides whether a hook gets to SEE the
+ * call. That makes it the mirror of a permission rule: a grant must hold for every
+ * segment and fails closed on anything it cannot read, while this runs the hook when any
+ * segment matches and when the input cannot be resolved at all. Claude: "When Claude Code
+ * can't determine which commands the Bash input runs, it runs your hook regardless of the
+ * pattern. Because the `if` filter is best-effort, use the permission system rather than
+ * a hook to enforce a hard allow or deny."
+ *
+ * Each top-level segment is checked with its leading assignments stripped, and so is the
+ * body of every substitution, since one can sit at any argument position. An unresolvable
+ * command name runs the hook whatever the pattern; a substitution anywhere runs it when
+ * the pattern names more than the command.
+ */
+export function matchesBashIfFilter(command: string, rule: string): boolean {
+  const trimmed = rule.trim()
+  const candidates = splitSegments(command).flatMap((segment) => {
+    const stripped = segment.replace(LEADING_ASSIGNMENTS, '')
+    return [stripped, ...substitutionBodies(stripped).flatMap((body) => splitSegments(body).map((inner) => inner.replace(LEADING_ASSIGNMENTS, '')))]
+  })
+  if (candidates.some((candidate) => matchesRule(candidate, trimmed))) return true
+  if (candidates.some(headUnresolvable)) return true
+  return namesMoreThanCommand(trimmed) && (hasSubstitution(command) || /\$[A-Za-z_{]/.test(command))
+}
+
 export function matchesBashRules(command: string, rules: string[]): boolean {
   if (hasSubstitution(command)) return false
   const segments = splitSegments(command)

package/extensions/internal/command-file.ts

@@ -377,7 +377,14 @@ export function substituteArgsDetailed(body: string, args: string, names: string
       return all || argsDefault
     }
     if (shorthandIdx !== undefined) return fill(parts[Number(shorthandIdx)], token)
-    if (name !== undefined) return fill(parts[names.indexOf(name)], '')
+    if (name !== undefined) {
+      // Claude: "A named placeholder counts even when its position has no argument,
+      // because it expands to an empty string", unlike an indexed one, which stays
+      // literal and does not count. Otherwise a skill using named arguments still got
+      // the ARGUMENTS: block appended.
+      consumed = true
+      return fill(parts[names.indexOf(name)], '')
+    }
     consumed = true
     return all // $ARGUMENTS or $@
   })

package/extensions/internal/effort.ts

@@ -0,0 +1,13 @@
+/**
+ * pi's thinking levels translated to Claude's effort vocabulary, which is
+ * `low | medium | high | xhigh | max`. pi adds two levels outside it: `minimal`, which
+ * reads as Claude's lowest, and `off`, which has no effort at all. Every surface that
+ * exposes the level to a script or a hook goes through here, so `off` and `minimal`
+ * never leak into a payload or an environment variable that promises Claude's set.
+ */
+
+/** The Claude effort level for a pi thinking level, or undefined when thinking is off. */
+export function claudeEffortLevel(thinkingLevel: string | undefined): string | undefined {
+  if (!thinkingLevel || thinkingLevel === 'off') return undefined
+  return thinkingLevel === 'minimal' ? 'low' : thinkingLevel
+}

package/extensions/internal/mcp-oauth.ts

@@ -121,8 +121,11 @@ export class FileOAuthProvider implements OAuthClientProvider {
     }
   }
 
+  /** The localhost spelling, which is what a server with a pre-registered redirect URI
+   * expects: Claude sent the 127.0.0.1 form for one version and "servers that exact-match
+   * the registered redirect URI rejected the sign-in with a redirect URI mismatch". */
   get redirectUrl(): string {
-    return `http://127.0.0.1:${this.port}/callback`
+    return `http://localhost:${this.port}/callback`
   }
 
   get clientMetadata(): OAuthClientMetadata {
@@ -193,13 +196,24 @@ export class FileOAuthProvider implements OAuthClientProvider {
  * taken, an ephemeral port is used. */
 export async function startCallbackServer(preferredPort?: number): Promise<{ server: http.Server; port: number }> {
   const server = http.createServer()
-  const listen = (port: number): Promise<void> => new Promise((resolve, reject) => server.listen(port, '127.0.0.1', resolve).once('error', reject))
+  const listen = (port: number, host: string): Promise<void> => new Promise((resolve, reject) => server.listen(port, host, resolve).once('error', reject))
   try {
-    await listen(preferredPort ?? 0)
+    await listen(preferredPort ?? 0, '127.0.0.1')
   } catch {
-    await listen(0)
+    await listen(0, '127.0.0.1')
   }
-  return { server, port: (server.address() as { port: number }).port }
+  const port = (server.address() as { port: number }).port
+  // The redirect names localhost, which resolves to ::1 first on a host with IPv6, so a
+  // second listener answers there too. Best effort: where it cannot bind, the IPv4
+  // listener above still answers every browser that resolves localhost to 127.0.0.1.
+  const ipv6 = http.createServer()
+  ipv6.on('error', () => {})
+  await new Promise<void>((resolve) => {
+    ipv6.listen(port, '::1', () => resolve()).once('error', () => resolve())
+  })
+  server.on('close', () => ipv6.close())
+  ipv6.on('request', (request, response) => server.emit('request', request, response))
+  return { server, port }
 }
 
 export function waitForAuthCode(server: http.Server, timeoutMs: number, expectedState?: string): Promise<string> {

package/extensions/internal/project-approval.ts

@@ -33,6 +33,8 @@ const CLAUDE_SHAPED = [
   path.join('.claude', 'rules'),
   path.join('.claude', 'skills'),
   path.join('.claude', 'commands'),
+  // Injected into the prompt verbatim, and context-imports treats it as approval-gated.
+  path.join('.claude', 'CLAUDE.md'),
   'CLAUDE.local.md',
   '.mcp.json',
   path.join('.pi', 'mcp.json'),

package/extensions/mcp/config.ts

@@ -21,6 +21,10 @@ export interface StdioServerConfig {
   timeout?: number
   /** Plugin servers alias their tools mcp__plugin_<plugin>_<server>__<tool>. */
   aliasPrefix?: string
+  /** The server name as its manifest declares it, without the plugin: scope the registry
+   * key carries. pi-side tool names derive from this, so a plugin server contributes
+   * <server>_<tool> the way a user server does. */
+  baseName?: string
   /** Root of the plugin that supplied this server; exported as CLAUDE_PLUGIN_ROOT. */
   pluginRoot?: string
   /** Loaded from the project scope, whose helpers run credential-stripped. */
@@ -42,6 +46,10 @@ export interface HttpServerConfig {
   timeout?: number
   /** Plugin servers alias their tools mcp__plugin_<plugin>_<server>__<tool>. */
   aliasPrefix?: string
+  /** The server name as its manifest declares it, without the plugin: scope the registry
+   * key carries. pi-side tool names derive from this, so a plugin server contributes
+   * <server>_<tool> the way a user server does. */
+  baseName?: string
   /** Root of the plugin that supplied this server; exported as CLAUDE_PLUGIN_ROOT. */
   pluginRoot?: string
   /** Loaded from the project scope, whose helpers run credential-stripped. */
@@ -213,7 +221,11 @@ export function loadPluginServers(plugins: InstalledPlugin[], projectDir?: strin
   for (const plugin of plugins) {
     for (const [name, config] of Object.entries(rawPluginServerEntries(plugin))) {
       const substituted = substitutedPluginServer(plugin, name, config, projectDir)
-      if (substituted) servers[name] = { ...substituted, aliasPrefix: `mcp__plugin_${fold(plugin.name)}_${fold(name)}__`, pluginRoot: plugin.root }
+      // Claude: "The server itself registers under the scoped name
+      // plugin:<plugin-name>:<server-name>", which is what an mcp_tool hook names and what
+      // keeps a same-named user server from replacing a plugin's. The tool alias keeps its
+      // own flat spelling, mcp__plugin_<plugin>_<server>__<tool>.
+      if (substituted) servers[`plugin:${plugin.name}:${name}`] = { ...substituted, aliasPrefix: `mcp__plugin_${fold(plugin.name)}_${fold(name)}__`, baseName: name, pluginRoot: plugin.root }
     }
   }
   return servers

package/extensions/mcp/index.ts

@@ -131,7 +131,9 @@ export default async function mcpExtension(pi: ExtensionAPI) {
   function registerTools(name: string, config: ServerConfig, tools: McpToolInfo[]): number {
     let count = 0
     for (const tool of tools) {
-      const toolName = formatToolName(name, tool.name)
+      // A plugin server's registry key carries its plugin: scope; its tools keep the bare
+      // server name, as their Claude alias does.
+      const toolName = formatToolName(config.baseName ?? name, tool.name)
       const owner = registered.get(toolName)
       if (owner === name) continue // already registered for this server: a refresh re-listing it
       if (RESERVED_NAMES.has(toolName) || owner !== undefined) {

package/extensions/mcp/oauth-flow.ts

@@ -28,6 +28,12 @@ function asOAuthRequiredError(name: string, error: unknown): OAuthRequiredError
  * (stored-token) connects do not pass through here and stay fully parallel. */
 let oauthQueue: Promise<unknown> = Promise.resolve()
 
+/** Test seam: the queue is module state that outlives a test, so one login left pending
+ * would serialize every later login in the same file behind it. */
+export function resetOAuthQueue(): void {
+  oauthQueue = Promise.resolve()
+}
+
 export function serializeInteractiveOAuth<T>(run: () => Promise<T>): Promise<T> {
   const result = oauthQueue.then(run, run)
   oauthQueue = result.then(

package/extensions/mcp/policy.ts

@@ -97,11 +97,19 @@ function parsePolicyEntry(entry: unknown): McpPolicyEntry | undefined {
  * honored scope sets the key; an empty list is an explicit lockdown (deny all). */
 export function mcpAllowDeny(scopeFiles: string[] = [], managedFile: string = managedSettingsFile()): McpPolicy {
   const read = (file: string): Record<string, unknown> => {
+    let raw: string
     try {
-      const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
+      raw = fs.readFileSync(file, 'utf-8')
+    } catch {
+      return {} // no such file: genuinely no policy
+    }
+    try {
+      const parsed = JSON.parse(raw)
       return parsed && typeof parsed === 'object' ? parsed : {}
     } catch {
-      // Missing or invalid file contributes no policy.
+      // Present but unreadable: its allow and deny lists are not in force, and a deny list
+      // silently dropped leaves every server allowed.
+      console.warn(`pi-code-mcp: ignoring ${file}: not valid JSON; its MCP allow and deny lists are not applied`)
       return {}
     }
   }

package/extensions/mcp/transport.ts

@@ -284,12 +284,33 @@ export async function connect(name: string, config: ServerConfig, authUi?: AuthU
   }
 }
 
+/** Transport-level failure codes worth another attempt. */
+const TRANSIENT_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EPIPE', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET'])
+
+/** Every `code` reachable from an error: its own, those of its `cause` chain, and those
+ * of an AggregateError's members. fetch reports a refused connection as a bare
+ * `TypeError: fetch failed` whose cause carries ECONNREFUSED, so the text says nothing. */
+function errorCodes(error: unknown, seen = new Set<unknown>()): string[] {
+  if (error === null || typeof error !== 'object' || seen.has(error)) return []
+  seen.add(error)
+  const codes: string[] = []
+  const code = (error as { code?: unknown }).code
+  if (typeof code === 'string') codes.push(code)
+  const inner = (error as { errors?: unknown }).errors
+  if (Array.isArray(inner)) for (const one of inner) codes.push(...errorCodes(one, seen))
+  codes.push(...errorCodes((error as { cause?: unknown }).cause, seen))
+  return codes
+}
+
 /** Whether a connect failure is worth retrying: a 5xx response, a refused or reset
- * connection, or a timeout. Auth and not-found errors need a configuration change. */
-function isTransientConnectError(error: unknown): boolean {
+ * connection, or a timeout, per Claude's "a 5xx response, a connection refused, or a
+ * timeout ... retries up to three times". Auth and not-found errors need a configuration
+ * change instead. Exported for the test that pins the shape node actually throws. */
+export function isTransientConnectError(error: unknown): boolean {
   if (isUnauthorized(error)) return false
-  const code = typeof error === 'object' && error !== null ? (error as { code?: unknown }).code : undefined
-  if (typeof code === 'number') return code >= 500
+  const status = typeof error === 'object' && error !== null ? (error as { code?: unknown }).code : undefined
+  if (typeof status === 'number') return status >= 500
+  if (errorCodes(error).some((code) => TRANSIENT_CODES.has(code))) return true
   return /ECONNREFUSED|ECONNRESET|ETIMEDOUT|timed out after/.test(String(error))
 }
 
@@ -315,9 +336,11 @@ export async function connectWithRetries(name: string, config: ServerConfig, aut
  * environment helperEnv built. It runs through the platform shell (/bin/sh; Git Bash
  * or PowerShell on Windows). A failure, a 10s timeout, or a machine with no shell
  * yields no extra headers rather than blocking the connection. */
-function runHeadersHelper(command: string, env: NodeJS.ProcessEnv): Promise<Record<string, string>> {
+export function runHeadersHelper(command: string, env: NodeJS.ProcessEnv, resolve_ = resolveShell): Promise<Record<string, string>> {
   return new Promise((resolve) => {
-    const shell = resolveShell(undefined)
+    // The resolver is a parameter so a test can drive both outcomes on any platform:
+    // stubbing the platform cannot produce a shell-less host on a machine that has one.
+    const shell = resolve_(undefined)
     if (!shell) {
       resolve({})
       return

package/extensions/memory.ts

@@ -80,6 +80,9 @@ export function resolveMemoryDir(cwd: string, override?: string): string {
 export function autoMemoryEnabled(setting: unknown, env: NodeJS.ProcessEnv): boolean {
   const disable = (env.CLAUDE_CODE_DISABLE_AUTO_MEMORY ?? '').trim().toLowerCase()
   if (disable === '1' || disable === 'true') return false
+  // Claude: "Set to 0 to force auto memory on even when --bare mode or
+  // autoMemoryEnabled: false would otherwise disable it."
+  if (disable === '0' || disable === 'false') return true
   return setting !== false
 }
 
@@ -536,7 +539,8 @@ export default function memoryExtension(pi: ExtensionAPI) {
         `  Auto memory: ${isEnabled ? 'on' : 'off'}`,
         `  Store:       ${store}`,
         `  Index:       ${path.join(store, INDEX_FILE)}`,
-        `  User memory (CLAUDE.md):    ${path.join(home, '.claude', 'CLAUDE.md')}`,
+        // The loader reads it from the configured directory, so CLAUDE_CONFIG_DIR moves it.
+        `  User memory (CLAUDE.md):    ${path.join(claudeConfigDir(home), 'CLAUDE.md')}`,
         `  Project memory (CLAUDE.md): ${path.join(ctx.cwd, 'CLAUDE.md')}`,
         // Claude's /memory lists every documented location, including files that
         // do not exist yet.

package/extensions/status-line.ts

@@ -31,8 +31,8 @@ import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
-
 import { hookFiles, readDisableAllHooks, runHookCommand } from './hooks/index.js'
+import { claudeEffortLevel } from './internal/effort.js'
 import { readManagedSettings } from './internal/managed-settings.js'
 import { isPlanModeState, PLAN_MODE_CHANNEL } from './internal/plan-mode-state.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
@@ -296,10 +296,10 @@ export default function statusLine(pi: ExtensionAPI) {
     const sessionName = ctx.sessionManager.getSessionName?.()
     if (sessionName) payload.session_name = sessionName
     if (ctx.thinkingLevel) {
-      // pi's off/minimal are outside Claude's effort vocabulary: minimal maps to
-      // low, and off omits effort entirely (thinking disabled says the rest).
+      // Thinking disabled says the rest, so off carries no effort field of its own.
       payload.thinking = { enabled: ctx.thinkingLevel !== 'off' }
-      if (ctx.thinkingLevel !== 'off') payload.effort = { level: ctx.thinkingLevel === 'minimal' ? 'low' : ctx.thinkingLevel }
+      const effort = claudeEffortLevel(ctx.thinkingLevel)
+      if (effort) payload.effort = { level: effort }
     }
     if (styleName) payload.output_style = { name: styleName }
     // The current utilization of the account's rate-limit windows, when the

package/extensions/subagent/index.ts

@@ -764,7 +764,7 @@ export function setKnownMcpAliases(aliases: ReadonlyArray<{ pi: string; claude:
 /** pi's built-in ToolName union (core/tools/index.d.ts; the package's export map
  * does not expose allToolNames, so this mirrors it) plus the tools pi-code's own
  * extensions register in a child. Claude's capitalized spellings fold onto these. */
-const CHILD_TOOL_NAMES = new Set(['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls', 'web_fetch', 'web_search', 'list_mcp_resources', 'read_mcp_resource'])
+const CHILD_TOOL_NAMES = new Set(['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls', 'web_fetch', 'web_search', 'list_mcp_resources', 'read_mcp_resource', 'todo', 'question', 'memory', 'slash_command', 'plan_mode_complete'])
 
 /** Claude: when no entry in a `tools` list resolves to a tool, the subagent fails
  * to launch with an error naming the entries, instead of running tool-less. */
@@ -785,7 +785,12 @@ function agentInvocationArgs(agent: AgentConfig, aliasModel?: string): string[]
   // order (invocation model, frontmatter model, this variable, the session model).
   // pi reads a thinking level from the model pattern's :suffix when a model is
   // pinned, and from --thinking otherwise.
-  const model = agent.model ?? aliasModel ?? process.env.CLAUDE_CODE_SUBAGENT_MODEL
+  // Claude exempts the two built-ins from the environment variable: "Setting
+  // CLAUDE_CODE_SUBAGENT_MODEL by itself doesn't change the model the built-in Explore and
+  // Plan subagents run on." A model they name themselves, or one the invocation names,
+  // still applies.
+  const exemptFromEnvModel = agent.source === 'builtin' && (agent.name === 'Explore' || agent.name === 'Plan')
+  const model = agent.model ?? aliasModel ?? (exemptFromEnvModel ? undefined : process.env.CLAUDE_CODE_SUBAGENT_MODEL)
   if (model) args.push('--model', agent.effort ? `${model}:${agent.effort}` : model)
   else if (agent.effort) args.push('--thinking', agent.effort)
   // Claude's mcp__<server> / mcp__* patterns expand against the parent's MCP roster;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "1.0.52",
+  "version": "1.0.54",
   "description": "Claude Code experience for the pi coding agent: reads your .claude config (rules, commands, skills, hooks, output styles, MCP servers, agents) and adds todo, checkpoints, memory, web, subagents, and goals",
   "keywords": [
     "pi",