pi-code 1.0.55 → 1.0.57

package/extensions/mcp/index.ts

@@ -44,6 +44,7 @@ import { installedPlugins } from '../internal/plugins.js'
 import { isProjectApproved, isProjectApprovedSilently } from '../internal/project-approval.js'
 import { repoRoot } from '../internal/project-root.js'
 import { claudeSettingsChain } from '../internal/settings-chain.js'
+import { errorMessage } from '../internal/values.js'
 import { disabledServerNames, loadConfigFrom, loadPluginServers, loadUserScope, localScopeServerNames, projectConfigPaths, type ServerConfig, warnOnTypelessUrl } from './config.js'
 import { collectServerResourceEntries, listAllPrompts, listAllTools, type McpToolInfo, resourceServerFilter } from './listing.js'
 import { formatPromptCommandName, formatToolName, type McpContentBlock, type McpPromptInfo, mapContent, mapPromptArguments, normalizeSchema, promptMessageContent } from './mapping.js'
@@ -272,7 +273,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
             // streaming, so mid-stream invocations queue as a follow-up turn.
             pi.sendUserMessage(content, ctx.isIdle() ? {} : { deliverAs: 'followUp' })
           } catch (error) {
-            ctx.ui.notify(`${commandName}: ${error instanceof Error ? error.message : String(error)}`, 'error')
+            ctx.ui.notify(`${commandName}: ${errorMessage(error)}`, 'error')
           }
         },
       })
@@ -286,7 +287,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     try {
       registerPrompts(name, await withTimeout(listAllPrompts(client), connectTimeoutMs(), `list prompts ${name}`))
     } catch (error) {
-      console.warn(`pi-code-mcp: prompt listing failed for ${name}: ${error instanceof Error ? error.message : String(error)}`)
+      console.warn(`pi-code-mcp: prompt listing failed for ${name}: ${errorMessage(error)}`)
     }
   }
 
@@ -298,7 +299,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
         try {
           registerPrompts(name, await withTimeout(listAllPrompts(client), connectTimeoutMs(), `list prompts ${name}`))
         } catch (error) {
-          console.warn(`pi-code-mcp: prompt refresh failed for ${name}: ${error instanceof Error ? error.message : String(error)}`)
+          console.warn(`pi-code-mcp: prompt refresh failed for ${name}: ${errorMessage(error)}`)
         }
       })
     } catch {
@@ -386,7 +387,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
           status.set(name, { state: current?.state ?? 'connected', tools: serverToolCount(name) })
           pi.events.emit(MCP_TOOLS_CHANNEL, [...aliases])
         } catch (error) {
-          console.warn(`pi-code-mcp: tool refresh failed for ${name}: ${error instanceof Error ? error.message : String(error)}`)
+          console.warn(`pi-code-mcp: tool refresh failed for ${name}: ${errorMessage(error)}`)
         }
       })
     } catch {
@@ -445,7 +446,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
             if (!shuttingDown && !serverCallTuning(config).stdio) void reconnectWithBackoff(name, config)
           }
         } catch (error) {
-          status.set(name, { state: `failed: ${error instanceof Error ? error.message : String(error)}`, tools: 0 })
+          status.set(name, { state: `failed: ${errorMessage(error)}`, tools: 0 })
           // Connected but failed after (tool listing hung or errored): left in the
           // map, the client idles its process for the whole session and the
           // duplicate-name guard blocks the name for every later attempt.

package/extensions/mcp/listing.ts

@@ -4,6 +4,7 @@
  */
 
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { errorMessage } from '../internal/values.js'
 import type { McpPromptInfo } from './mapping.js'
 import { callRequestOptions, withTimeout } from './transport.js'
 
@@ -76,7 +77,7 @@ export async function collectServerResourceEntries(entries: Array<Record<string,
   try {
     await collectResources(entries, name, client, budget)
   } catch (error) {
-    entries.push({ server: name, error: error instanceof Error ? error.message : String(error) })
+    entries.push({ server: name, error: errorMessage(error) })
   }
   try {
     await collectResourceTemplates(entries, name, client, budget)

package/extensions/mcp/oauth-flow.ts

@@ -7,6 +7,7 @@
 
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
 import { FileOAuthProvider, type OAuthServerConfig, openBrowser, startCallbackServer, waitForAuthCode } from '../internal/mcp-oauth.js'
+import { errorMessage } from '../internal/values.js'
 import { type AuthUi, connectWithTimeout, isUnauthorized, type MakeTransport, OAuthRequiredError } from './transport.js'
 
 /** Browser logins are human-paced; a connect-sized timeout would cut them off. */
@@ -16,7 +17,7 @@ const OAUTH_FLOW_TIMEOUT_MS = 180_000
  * unchanged so its message is not doubled. */
 function asOAuthRequiredError(name: string, error: unknown): OAuthRequiredError {
   if (error instanceof OAuthRequiredError) return error
-  const detail = error instanceof Error ? error.message : String(error)
+  const detail = errorMessage(error)
   return new OAuthRequiredError(`login for ${name} failed: ${detail}`)
 }
 

package/extensions/mcp/policy.ts

@@ -9,6 +9,7 @@ import * as path from 'node:path'
 import { claudeConfigDir } from '../internal/config-dir.js'
 import { managedSettingsFile } from '../internal/managed-settings.js'
 import { findNearestFile } from '../internal/project-root.js'
+import { errorMessage } from '../internal/values.js'
 import { interpolateEnv, type ServerConfig } from './config.js'
 
 export interface ProjectServerPolicy {
@@ -151,7 +152,13 @@ export function urlPatternMatches(pattern: string, url: string): boolean {
   return wildcardRegExp(patternParts.path).test(urlParts.path ?? '/')
 }
 
-const configUrl = (config: ServerConfig): string | undefined => (config as { url?: string }).url
+/** A config file is user- or repo-written JSON, so any field can hold any value. Only a
+ * string `url` makes a server remote: a config that carries some other value there is
+ * still gated by its command, and no policy entry is evaluated against a non-string. */
+const configUrl = (config: ServerConfig): string | undefined => {
+  const url = (config as { url?: unknown }).url
+  return typeof url === 'string' ? url : undefined
+}
 const configArgv = (config: ServerConfig): string[] | undefined => {
   const command = (config as { command?: string }).command
   if (typeof command !== 'string') return undefined
@@ -227,7 +234,7 @@ export function loadManagedMcpServers(managedFile: string = managedSettingsFile(
   } 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)}`)
+    console.warn(`pi-code-mcp: managed-mcp.json is present but not valid JSON (${file}); failing closed to no MCP servers: ${errorMessage(error)}`)
     return {}
   }
   if (parsed === null || typeof parsed !== 'object') return {}

package/extensions/memory.ts

@@ -20,8 +20,9 @@ import { readManagedSettings } from './internal/managed-settings.js'
 import { capForContext } from './internal/output-guard.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { repoRoot } from './internal/project-root.js'
-import { claudeSettingsChain } from './internal/settings-chain.js'
+import { claudeSettingsChain, readSettingsChain } from './internal/settings-chain.js'
 import { statToken } from './internal/stat-token.js'
+import { errorMessage } from './internal/values.js'
 
 export const INDEX_FILE = 'MEMORY.md'
 
@@ -152,7 +153,7 @@ export function migrateLegacyStore(cwd: string): void {
     } catch (error) {
       // A failed migration must not take down session start, but the session then has no
       // memories while they sit under the old slug, which reads as having lost them.
-      console.warn(`pi-code-memory: could not move ${legacy} to ${current}: ${error instanceof Error ? error.message : String(error)}; this session starts without those memories`)
+      console.warn(`pi-code-memory: could not move ${legacy} to ${current}: ${errorMessage(error)}; this session starts without those memories`)
     }
     return
   }
@@ -236,7 +237,7 @@ function readMemory(dir: string, name: string): MemoryToolResult {
     // Only a missing file is "no such memory"; anything else (a directory in its place, a
     // permission problem) sends the model hunting for a name that is actually there.
     if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
-      return { content: [{ type: 'text', text: `Memory ${name} could not be read: ${error instanceof Error ? error.message : String(error)}` }], details: {} }
+      return { content: [{ type: 'text', text: `Memory ${name} could not be read: ${errorMessage(error)}` }], details: {} }
     }
     return { content: [{ type: 'text', text: `No memory named ${name}.` }], details: {} }
   }
@@ -257,7 +258,7 @@ async function deleteMemory(dir: string, indexPath: string, name: string): Promi
       return { content: [{ type: 'text', text: `Deleted memory ${name}.` }], details: {} }
     })
   } catch (error) {
-    return { content: [{ type: 'text', text: `Memory delete failed: ${error instanceof Error ? error.message : String(error)}. Nothing was deleted.` }], details: {} }
+    return { content: [{ type: 'text', text: `Memory delete failed: ${errorMessage(error)}. Nothing was deleted.` }], details: {} }
   }
 }
 
@@ -350,15 +351,9 @@ export function memorySettingsFiles(cwd: string, home: string, approved: boolean
  * managed policy settings win over every file, per Claude's settings precedence. */
 export function readMemorySettings(files: string[], managed: Record<string, unknown> = readManagedSettings()): { autoMemoryEnabled?: unknown; autoMemoryDirectory?: unknown } {
   const merged: { autoMemoryEnabled?: unknown; autoMemoryDirectory?: unknown } = {}
-  for (const file of files) {
-    try {
-      const settings = JSON.parse(fs.readFileSync(file, 'utf-8'))
-      if (settings === null || typeof settings !== 'object') continue
-      if ('autoMemoryEnabled' in settings) merged.autoMemoryEnabled = settings.autoMemoryEnabled
-      if ('autoMemoryDirectory' in settings) merged.autoMemoryDirectory = settings.autoMemoryDirectory
-    } catch {
-      // missing or invalid settings file: skip
-    }
+  for (const settings of readSettingsChain(files)) {
+    if ('autoMemoryEnabled' in settings) merged.autoMemoryEnabled = settings.autoMemoryEnabled
+    if ('autoMemoryDirectory' in settings) merged.autoMemoryDirectory = settings.autoMemoryDirectory
   }
   if ('autoMemoryEnabled' in managed) merged.autoMemoryEnabled = managed.autoMemoryEnabled
   if ('autoMemoryDirectory' in managed) merged.autoMemoryDirectory = managed.autoMemoryDirectory
@@ -478,7 +473,7 @@ export default function memoryExtension(pi: ExtensionAPI) {
           // Awaited here, not returned: the catch must see a queued write's rejection.
           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: {} }
+          return { content: [{ type: 'text' as const, text: `Memory save failed: ${errorMessage(error)}. The index was left untouched.` }], details: {} }
         } finally {
           indexCache = null
         }
@@ -520,7 +515,7 @@ export default function memoryExtension(pi: ExtensionAPI) {
         try {
           result = setAutoMemoryEnabledSetting(home, next)
         } catch (error) {
-          ctx.ui.notify(`Could not update auto memory: ${error instanceof Error ? error.message : String(error)}`, 'error')
+          ctx.ui.notify(`Could not update auto memory: ${errorMessage(error)}`, 'error')
           return
         }
         if (!result.ok) {

package/extensions/output-styles.ts

@@ -24,13 +24,13 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 import { atomicWriteFile } from './internal/atomic-write.js'
-
 import { claudeConfigDir } from './internal/config-dir.js'
 import { readManagedSettings } from './internal/managed-settings.js'
 import { installedPlugins, pluginComponentPath } from './internal/plugins.js'
 import { isProjectApproved } from './internal/project-approval.js'
 import { ancestorDirs, findNearestDir, findNearestFile } from './internal/project-root.js'
-import { claudeSettingsChain } from './internal/settings-chain.js'
+import { claudeSettingsChain, readSettingsChain } from './internal/settings-chain.js'
+import { isDirectory } from './internal/values.js'
 
 export interface OutputStyle {
   name: string
@@ -87,14 +87,6 @@ export function applyStyle(systemPrompt: string, style: OutputStyle): string {
   return `${systemPrompt}\n\n${styleSection}`
 }
 
-function isDirectory(target: string): boolean {
-  try {
-    return fs.statSync(target).isDirectory()
-  } catch {
-    return false
-  }
-}
-
 /**
  * Existing `.claude/output-styles` directories, user first then project. The project
  * directory is included only for trusted projects, since its style body is injected
@@ -159,13 +151,8 @@ export function settingsFiles(cwd: string, home: string, trusted: boolean): stri
 export function readActiveStyleName(files: string[], managed: Record<string, unknown> = readManagedSettings()): string | undefined {
   if (typeof managed.outputStyle === 'string') return managed.outputStyle
   let name: string | undefined
-  for (const file of files) {
-    try {
-      const settings = JSON.parse(fs.readFileSync(file, 'utf-8'))
-      if (typeof settings.outputStyle === 'string') name = settings.outputStyle
-    } catch {
-      // missing or invalid file: skip
-    }
+  for (const settings of readSettingsChain(files)) {
+    if (typeof settings.outputStyle === 'string') name = settings.outputStyle
   }
   return name
 }

package/extensions/plan-mode/index.ts

@@ -19,7 +19,7 @@ import { Key } from '@earendil-works/pi-tui'
 import { Type } from 'typebox'
 
 import { PLAN_MODE_CHANNEL } from '../internal/plan-mode-state.js'
-import { extractTodoItems, isSafeCommand, markCompletedSteps, planToTodos, type TodoItem } from './utils.js'
+import { extractTodoItems, isSafeCommand, markCompletedSteps, planToTodos, restoredPlanState, type TodoItem } from './utils.js'
 
 // Tools
 const PLAN_MODE_TOOLS = ['read', 'bash', 'grep', 'find', 'ls', 'question', 'plan_mode_complete']
@@ -433,14 +433,14 @@ After completing a step, include a [DONE:n] tag in your response.`,
     // rewind past a plan it would resurrect the abandoned plan and its tool restriction.
     const entries = ctx.sessionManager.getBranch()
 
-    // Restore persisted state
-    const planModeEntry = findLast(entries, (e: { type: string; customType?: string }) => e.type === 'custom' && e.customType === 'plan-mode') as { data?: { enabled: boolean; todos?: TodoItem[]; executing?: boolean; savedTools?: string[] } } | undefined
+    // Restore persisted state. The entry is JSON on disk, so every field is checked
+    // before it is used: savedTools reaches pi.setActiveTools.
+    const planModeEntry = findLast(entries, (e: { type: string; customType?: string }) => e.type === 'custom' && e.customType === 'plan-mode') as { data?: unknown } | undefined
+    const restored = restoredPlanState(planModeEntry?.data)
 
-    if (planModeEntry?.data) {
-      planModeEnabled = planModeEntry.data.enabled ?? planModeEnabled
-      todoItems = planModeEntry.data.todos ?? todoItems
-      executionMode = planModeEntry.data.executing ?? executionMode
-    }
+    planModeEnabled = restored.enabled ?? planModeEnabled
+    todoItems = restored.todos ?? todoItems
+    executionMode = restored.executing ?? executionMode
     publishPlanState()
 
     // On resume: re-scan messages after the last "plan-mode-execute" to rebuild
@@ -456,7 +456,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
       // across /reload and cost the session edit and write for good; applying the
       // snapshot when plan mode is off would instead push a stale set over whatever
       // pi has registered since, so it stays scoped to this branch.
-      savedTools = planModeEntry?.data?.savedTools ?? pi.getActiveTools()
+      savedTools = restored.savedTools ?? pi.getActiveTools()
       pi.setActiveTools(PLAN_MODE_TOOLS.filter((t) => savedTools.includes(t)))
       // --plan enters plan mode without ever toggling, so nothing has persisted yet
       // and a /reload would find no snapshot to restore from. Record it now, while

package/extensions/plan-mode/utils.ts

@@ -120,6 +120,37 @@ export interface TodoItem {
   completed: boolean
 }
 
+/** The plan state persisted in a session entry, once each field has been checked.
+ * A field the restore cannot recognize is simply absent, so the caller keeps its
+ * current value. */
+export interface RestoredPlanState {
+  enabled?: boolean
+  todos?: TodoItem[]
+  executing?: boolean
+  savedTools?: string[]
+}
+
+const isTodoItem = (value: unknown): value is TodoItem => {
+  if (value === null || typeof value !== 'object') return false
+  const item = value as Record<string, unknown>
+  return typeof item.step === 'number' && typeof item.text === 'string' && typeof item.completed === 'boolean'
+}
+
+/** Read a persisted plan-mode entry, keeping only fields of the expected shape.
+ * The session file is data on disk, and `savedTools` feeds the active tool set: a
+ * string there would be spread character by character into the tool gating, and a
+ * non-array `todos` throws on the first restore that iterates it. */
+export function restoredPlanState(data: unknown): RestoredPlanState {
+  if (data === null || typeof data !== 'object') return {}
+  const raw = data as Record<string, unknown>
+  const state: RestoredPlanState = {}
+  if (typeof raw.enabled === 'boolean') state.enabled = raw.enabled
+  if (typeof raw.executing === 'boolean') state.executing = raw.executing
+  if (Array.isArray(raw.todos) && raw.todos.every(isTodoItem)) state.todos = raw.todos
+  if (Array.isArray(raw.savedTools) && raw.savedTools.every((tool) => typeof tool === 'string')) state.savedTools = raw.savedTools
+  return state
+}
+
 function cleanStepText(text: string): string {
   let cleaned = text
     .replace(/\*{1,2}([^*]+)\*{1,2}/g, '$1') // Remove bold/italic

package/extensions/session-title.ts

@@ -21,6 +21,7 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 
 import { completeText } from './internal/model-complete.js'
+import { contentText } from './internal/values.js'
 
 const TITLE_SYSTEM = 'You name a coding session from its first user message. Reply with a terse 3 to 6 word title in Title Case that captures the task. No quotes, no surrounding punctuation, no trailing period. Output the title only, nothing else.'
 /** A title is a few words; a tight cap keeps the extra call cheap and stops a runaway reply. */
@@ -29,23 +30,12 @@ const TITLE_MAX_TOKENS = 24
  * bounded prompt keeps the input cost of the extra call small. */
 const MAX_PROMPT_CHARS = 1000
 
-/** Join the text of a message's content, mirroring git-checkpoint's extraction: content is
- * either a plain string or an array of parts, of which only text parts carry a title's worth. */
-function extractText(content: unknown): string {
-  if (typeof content === 'string') return content
-  if (!Array.isArray(content)) return ''
-  return content
-    .filter((part) => part?.type === 'text' && typeof part.text === 'string')
-    .map((part) => part.text)
-    .join(' ')
-}
-
 /** Text of the first user message in the branch, or empty when the run carried no user text
  * (for example a slash-command-only turn), in which case there is nothing to title from. */
 export function firstUserText(ctx: ExtensionContext): string {
   for (const entry of ctx.sessionManager.getBranch()) {
     if (entry?.type === 'message' && entry.message.role === 'user') {
-      return extractText(entry.message.content).trim()
+      return contentText(entry.message.content, ' ').trim()
     }
   }
   return ''

package/extensions/skills.ts

@@ -23,7 +23,6 @@ import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 import { type ExtensionAPI, type ExtensionContext, parseFrontmatter } from '@earendil-works/pi-coding-agent'
-
 import { expandCommand, shellExecutionDisabled } from './commands.js'
 import { runAgent } from './internal/agent-run.js'
 import { parseCommandFile } from './internal/command-file.js'
@@ -32,16 +31,9 @@ import { managedSettingsFile } from './internal/managed-settings.js'
 import { installedPlugins, pluginComponentPath } from './internal/plugins.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { ancestorDirs } from './internal/project-root.js'
-import { claudeSettingsChain } from './internal/settings-chain.js'
+import { claudeSettingsChain, readSettingsChain } from './internal/settings-chain.js'
 import { SKILL_HOOKS_CHANNEL } from './internal/skill-hooks.js'
-
-function isDirectory(target: string): boolean {
-  try {
-    return fs.statSync(target).isDirectory()
-  } catch {
-    return false
-  }
-}
+import { errorMessage, isDirectory, isRecord } from './internal/values.js'
 
 /** Existing `.claude/skills` directories, user first then project. The project
  * directory is included only for approved projects: pi's loader surfaces every skill's
@@ -136,13 +128,9 @@ export default function skillsExtension(pi: ExtensionAPI) {
  * (a pi-loader surface, noted in docs). */
 function skillOverrideFor(name: string, cwd: string, trusted: boolean): string | undefined {
   let value: string | undefined
-  for (const file of claudeSettingsChain(cwd, os.homedir(), trusted)) {
-    try {
-      const overrides = JSON.parse(fs.readFileSync(file, 'utf-8')).skillOverrides
-      if (overrides !== null && typeof overrides === 'object' && typeof overrides[name] === 'string') value = overrides[name]
-    } catch {
-      // missing or invalid file: skip
-    }
+  for (const settings of readSettingsChain(claudeSettingsChain(cwd, os.homedir(), trusted))) {
+    const overrides = settings.skillOverrides
+    if (isRecord(overrides) && typeof overrides[name] === 'string') value = overrides[name]
   }
   return value
 }
@@ -165,7 +153,7 @@ async function runForkedSkill(name: string, filePath: string, expanded: string,
     const output = await runAgent({ prompt: expanded, fullTools: true, ...(agentName ? { agent: agentName } : {}) })
     return { action: 'transform', text: `<skill name="${name}" location="${filePath}">\nThe skill ran in a forked subagent (no conversation history shared). Its result:\n\n${output}\n</skill>` }
   } catch (error) {
-    return { action: 'transform', text: `<skill name="${name}">\nThe forked subagent run failed: ${error instanceof Error ? error.message : String(error)}\n</skill>` }
+    return { action: 'transform', text: `<skill name="${name}">\nThe forked subagent run failed: ${errorMessage(error)}\n</skill>` }
   }
 }
 

package/extensions/status-line.ts

@@ -36,6 +36,7 @@ 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'
+import { readSettingsChain } from './internal/settings-chain.js'
 import { watchSettingsFiles } from './internal/settings-watch.js'
 import { readActiveStyleName, settingsFiles } from './output-styles.js'
 
@@ -178,14 +179,7 @@ export function readStatusLineConfig(files: string[], managed: Record<string, un
   if (managedConfig) return managedConfig
   if (managed.allowManagedHooksOnly === true) return undefined
   let found: StatusLineConfig | undefined
-  for (const file of files) {
-    try {
-      const settings = JSON.parse(fs.readFileSync(file, 'utf-8'))
-      found = parseStatusLineEntry(settings.statusLine) ?? found
-    } catch {
-      // missing or invalid file: skip
-    }
-  }
+  for (const settings of readSettingsChain(files)) found = parseStatusLineEntry(settings.statusLine) ?? found
   return found
 }
 

package/extensions/subagent/README.md

@@ -18,9 +18,19 @@ Delegate tasks to specialized subagents with isolated context windows.
 ```
 subagent/
 ├── README.md            # This file
-├── index.ts             # The extension (entry point)
-├── agents.ts            # Agent discovery logic
+├── index.ts             # The extension: tool schema, dispatch, session hooks
+├── agents.ts            # Agent discovery and frontmatter
+├── child.ts             # How a child is configured before it is spawned
+├── run.ts               # Spawning one child and parsing its event stream
+├── modes.ts             # Single, parallel, chain, background, and the project-agent gate
 ├── background.ts        # Background run registry and spawning
+├── worktree.ts          # isolation: worktree setup and teardown
+├── params.ts            # The tool schema and the types derived from it
+├── types.ts             # Result shapes shared by the tool and its renderers
+├── concurrency.ts       # Parallel-run caps and the bounded worker pool
+├── registry-text.ts     # Text for /tasks, /agents and completion notices
+├── render.ts            # Transcript formatting shared with the parent
+├── render-result.ts     # How a call and its results are drawn
 ├── agents/              # Bundled builtin agents, always available (lowest precedence)
 │   ├── explore.md       # Explore: fast read-only codebase exploration
 │   ├── plan.md          # Plan: read-only implementation planning
@@ -39,7 +49,7 @@ This tool executes a separate `pi` subprocess with a delegated system prompt and
 
 **Default behavior:** Loads the bundled builtin agents (Explore, Plan, general-purpose) plus **user-level agents** from `~/.claude/agents` and `~/.pi/agent/agents`. A user or project agent with the same name overrides a builtin. Discovered agents and their descriptions are listed in the system prompt each turn, so the model can pick one itself; project agent descriptions appear only once the project is approved.
 
-To enable project-local agents (`.claude/agents`, `.pi/agents`), pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
+Project-local agents (`.claude/agents`, `.pi/agents`) load once the project is approved: a default call resolves `agentScope` to `"both"` for an approved project and `"user"` otherwise, and an explicit `agentScope` still narrows or widens it. Every invocation passes the project-agent gate either way.
 
 When running interactively, the tool prompts for confirmation before running project-local agents. `confirmProjectAgents: false` skips that prompt for a project you have already approved; an unapproved project is still asked about.
 
@@ -134,9 +144,9 @@ enforces per call.
 
 **Locations:**
 - `~/.claude/agents/*.md`, `~/.pi/agent/agents/*.md` - User-level (always loaded; `~/.pi` wins a name conflict)
-- `.claude/agents/*.md`, `.pi/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`; `.pi` wins a name conflict)
+- `.claude/agents/*.md`, `.pi/agents/*.md` - Project-level (an approved project, or an explicit `agentScope` of `"project"`/`"both"`; `.pi` wins a name conflict)
 
-Project agents override user agents with the same name when `agentScope: "both"`.
+Project agents override user agents with the same name when both scopes are in play.
 
 ## Builtin Agents
 

package/extensions/subagent/agents.ts

@@ -6,7 +6,6 @@ import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 import { getAgentDir, parseFrontmatter, stripFrontmatter } from '@earendil-works/pi-coding-agent'
-
 // The same mapping a command's `allowed-tools` gets: an agent's `tools:` is the same
 // Claude field, and `--tools` is an exact-name allowlist, so a name pi has no tool for
 // is not merely ignored, it narrows the child's registry.
@@ -14,6 +13,7 @@ import { parseToolGrants } from '../internal/command-file.js'
 import { claudeConfigDir } from '../internal/config-dir.js'
 import { installedPlugins, pluginComponentPath } from '../internal/plugins.js'
 import { ancestorDirs, findNearestDir } from '../internal/project-root.js'
+import { errorMessage } from '../internal/values.js'
 
 /**
  * `tools:` may be a comma-separated string (the Claude Code format) or a YAML block
@@ -180,7 +180,7 @@ function parseAgentFile(content: string, source: AgentSource, filePath: string,
   } catch (error) {
     // Malformed YAML must not abort discovery for the whole directory, but a silent drop
     // reads as "that agent does not exist", so it is named like the other rejections here.
-    console.warn(`pi-code-subagent: ignoring agent ${filePath}: its frontmatter could not be parsed (${error instanceof Error ? error.message : String(error)})`)
+    console.warn(`pi-code-subagent: ignoring agent ${filePath}: its frontmatter could not be parsed (${errorMessage(error)})`)
     return null
   }
   const { frontmatter, body } = parsed

package/extensions/subagent/background.ts

@@ -11,6 +11,7 @@ import { randomUUID } from 'node:crypto'
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
+import { errorMessage } from '../internal/values.js'
 
 export interface BackgroundRun {
   id: string
@@ -245,7 +246,7 @@ function withRebuiltPrompt(spawnSpec: BackgroundSpawn, agent: string): { args: s
     // prompt text, which would replace the agent persona with a temp path. The child then
     // runs as a plain assistant instead of the agent asked for, and nothing in its output
     // says so, hence the notice.
-    console.warn(`pi-code-subagent: resuming ${agent} without its agent prompt: ${error instanceof Error ? error.message : String(error)}`)
+    console.warn(`pi-code-subagent: resuming ${agent} without its agent prompt: ${errorMessage(error)}`)
     return { args: spawnSpec.args.filter((_arg, i) => i !== flag && i !== flag + 1) }
   }
 }