pi-code 1.0.56 → 1.0.58

package/extensions/claude-rules.ts

@@ -29,6 +29,7 @@ import { type CompiledGlob, compileGlobs, matchesCompiledGlobs } from './interna
 import { isProjectApproved } from './internal/project-approval.js'
 import { findNearestDir } from './internal/project-root.js'
 import { stripBlockComments } from './internal/strip-comments.js'
+import { fileToolTarget } from './internal/tool-target.js'
 
 export interface Frontmatter {
   paths: string[]
@@ -341,10 +342,8 @@ export default function claudeRulesExtension(pi: ExtensionAPI) {
   // read or edited rather than inlining it upfront.
   pi.on('tool_result', async (event, ctx) => {
     if (attachTargets.length === 0) return
-    if (event.isError) return
-    if (event.toolName !== 'read' && event.toolName !== 'edit' && event.toolName !== 'write') return
-    const rel = (event.input as { path?: unknown } | undefined)?.path
-    if (typeof rel !== 'string' || rel.length === 0) return
+    const rel = fileToolTarget(event)
+    if (rel === undefined) return
     // Realpath both sides (roots canonicalise at session_start): a tool reporting
     // the resolved real path in a symlinked checkout must still match.
     const abs = realpathOr(path.resolve(ctx.cwd, rel))

package/extensions/commands.ts

@@ -44,7 +44,8 @@ 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 { type DiscoveredCommand, discoverCommandFiles, type ParsedCommand, type PathRuleTool, parseCommandFile, substituteArgsDetailed, substituteVars } from './internal/command-file.js'
+import { type CommandExec, expandDynamicContent, resolvePowershellBinary, spanExec } from './internal/command-spans.js'
 import { claudeConfigDir } from './internal/config-dir.js'
 import { claudeEffortLevel } from './internal/effort.js'
 import { managedSettingsFile, readManagedSettings } from './internal/managed-settings.js'
@@ -55,6 +56,7 @@ import { isProjectApproved } from './internal/project-approval.js'
 import { ancestorDirs, repoRoot } from './internal/project-root.js'
 import { claudeSettingsChain } from './internal/settings-chain.js'
 import { createTurnOverride } from './internal/turn-override.js'
+import { errorMessage, isDirectory } from './internal/values.js'
 
 /** Just enough of pi's Model to match and restore; getAvailable returns these. */
 interface ModelLike {
@@ -105,14 +107,6 @@ interface VarContext {
   modelRegistry?: { getAvailable(): ReadonlyArray<ModelLike> }
 }
 
-function isDirectory(target: string): boolean {
-  try {
-    return fs.statSync(target).isDirectory()
-  } catch {
-    return false
-  }
-}
-
 /** Existing `.claude/commands` directories in Claude's precedence order (later
  * directories win in collectCommands): project first, then personal, then the
  * enterprise directory beside the managed settings file, per "enterprise
@@ -328,7 +322,7 @@ export default function commandsExtension(pi: ExtensionAPI) {
       // A refused switch leaves the turn on the session model rather than the one the
       // command named, and the reply gives no sign of it, so the refusal is reported.
       void pi.setModel(model as Parameters<typeof pi.setModel>[0]).catch((error: unknown) => {
-        console.warn(`pi-code-commands: could not switch to ${typeof model === 'object' && model !== null && 'id' in model ? String((model as { id: unknown }).id) : String(model)}: ${error instanceof Error ? error.message : String(error)}`)
+        console.warn(`pi-code-commands: could not switch to ${typeof model === 'object' && model !== null && 'id' in model ? String((model as { id: unknown }).id) : String(model)}: ${errorMessage(error)}`)
       })
     },
   })
@@ -455,7 +449,7 @@ export default function commandsExtension(pi: ExtensionAPI) {
     } catch (error) {
       // A failed injected command aborts the invocation; the model never sees a
       // half-expanded body. The notify carries Claude's failure message format.
-      ctx.ui.notify(error instanceof Error ? error.message : String(error), 'error')
+      ctx.ui.notify(errorMessage(error), 'error')
       return
     }
 
@@ -513,7 +507,7 @@ export default function commandsExtension(pi: ExtensionAPI) {
         // An unreadable file must not take down session start, but the command is then
         // absent from /help and unresolvable by the model, which looks like one that was
         // never written.
-        console.warn(`pi-code-commands: ignoring ${command.filePath}: ${error instanceof Error ? error.message : String(error)}`)
+        console.warn(`pi-code-commands: ignoring ${command.filePath}: ${errorMessage(error)}`)
         continue
       }
       discovered.set(command.name, command)

package/extensions/context-imports.ts

@@ -72,13 +72,14 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 import { claudeConfigDir } from './internal/config-dir.js'
 import { type InstructionLoadEvent, memoryTypeForPath, publishInstructionLoad } from './internal/instruction-events.js'
 import { managedSettingsPath, readManagedSettings } from './internal/managed-settings.js'
-import { sliceBytes } from './internal/output-guard.js'
+import { capForContext, sliceBytes } from './internal/output-guard.js'
 import { globToRegExpSource } from './internal/path-rules.js'
-import { isProjectApproved, isProjectApprovedSilently } from './internal/project-approval.js'
+import { isGatedFileApproved, isProjectApproved, isProjectApprovedSilently } from './internal/project-approval.js'
 import { ancestorFiles, findNearestFile, 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 { type Fence, fenceMarker, stepFence, stripBlockComments } from './internal/strip-comments.js'
+import { fileToolTarget } from './internal/tool-target.js'
 
 /** Claude documents "a maximum depth of four hops" for recursive imports. */
 const MAX_IMPORT_DEPTH = 4
@@ -138,9 +139,12 @@ export interface ImportBudget {
   files: number
   bytes: number
   dropped: number
+  /** Existing files an @import named that resolve outside the importer's allowed
+   * roots. Collected so the refusal can be reported rather than left silent. */
+  refused: Set<string>
 }
 
-export const createImportBudget = (): ImportBudget => ({ files: MAX_IMPORT_FILES, bytes: MAX_IMPORT_BYTES, dropped: 0 })
+export const createImportBudget = (): ImportBudget => ({ files: MAX_IMPORT_FILES, bytes: MAX_IMPORT_BYTES, dropped: 0, refused: new Set() })
 
 /** The `@path` targets of a context file, in document order. Claude Code evaluates
  * imports neither in fenced code blocks (backtick or tilde) nor in inline spans. */
@@ -162,16 +166,28 @@ function importTargets(content: string): string[] {
 }
 
 /** Read one `@path` target, or null when it is unresolvable, already seen, outside `allowedRoots`, excluded, or unreadable. */
-function readImport(target: string, fromDir: string, home: string, allowedRoots: string[], seen: Set<string>, isExcluded?: (realPath: string) => boolean): { real: string; body: string } | null {
+function readImport(target: string, fromDir: string, home: string, allowedRoots: string[], seen: Set<string>, isExcluded: ((realPath: string) => boolean) | undefined, refused: Set<string>): { real: string; body: string } | null {
   const resolved = path.resolve(fromDir, expandHome(target, home))
+  // Always the path the importing file named, never where a symlink pointed: the
+  // notice would otherwise hand a repo the real name of whatever the link reaches,
+  // which is the disclosure the refusal exists to prevent. An excluded file is not
+  // named either, since exclusion removes it from every other surface too.
+  const refuse = (): null => {
+    if (isExcluded?.(resolved) !== true) refused.add(resolved)
+    return null
+  }
   let real: string
   try {
     real = fs.realpathSync(resolved)
   } catch {
-    return null
+    // Not on disk. Still refused when it points outside, so that whether a path is
+    // reported never depends on whether it exists: a notice that named only the
+    // existing ones would enumerate the filesystem for any repo-controlled file
+    // willing to write one @line per guess.
+    return isUnder(resolved, allowedRoots) ? null : refuse()
   }
   if (seen.has(real)) return null
-  if (!isUnder(real, allowedRoots)) return null
+  if (!isUnder(real, allowedRoots)) return refuse()
   // Checked before the read so an excluded file contributes nothing: no body, no
   // transitive imports, no budget spend, no announce. A post-collection filter
   // would drop the file itself but keep its children.
@@ -182,6 +198,9 @@ function readImport(target: string, fromDir: string, home: string, allowedRoots:
     // Only a consumed file dedupes: marking a blocked or unreadable target seen
     // would let one reader's failure suppress the import for a later, allowed one.
     seen.add(real)
+    // A file another importer already refused is in context after all; the notice
+    // must not claim otherwise.
+    refused.delete(resolved)
     return { real, body }
   } catch {
     return null
@@ -218,7 +237,7 @@ function collectFrom(scan: ImportScan, content: string, fromDir: string, depth:
       scan.budget.dropped += 1
       continue
     }
-    const file = readImport(target, fromDir, scan.home, scan.allowedRoots, scan.seen, scan.isExcluded)
+    const file = readImport(target, fromDir, scan.home, scan.allowedRoots, scan.seen, scan.isExcluded, scan.budget.refused)
     if (!file) continue
     scan.budget.files -= 1
     // The budget is bytes: a string slice counts UTF-16 units and lets CJK text through
@@ -406,15 +425,7 @@ export function readClaudeMdExcludes(files: string[], managed: Record<string, un
       if (typeof entry === 'string' && entry.trim().length > 0) globs.push(entry)
     }
   }
-  for (const file of files) {
-    try {
-      const settings = JSON.parse(fs.readFileSync(file, 'utf-8'))
-      if (settings === null || typeof settings !== 'object') continue
-      collect((settings as Record<string, unknown>).claudeMdExcludes)
-    } catch {
-      // missing or invalid settings file: skip
-    }
-  }
+  for (const settings of readSettingsChain(files)) collect(settings.claudeMdExcludes)
   collect(managed.claudeMdExcludes)
   return globs
 }
@@ -505,6 +516,156 @@ function expandImports(contextFiles: Array<{ path: string; content: string }>, e
   return imported
 }
 
+/** Every context file that could load on demand for a touched directory, shallowest
+ * first, so the deepest instructions are read last as they are at launch. */
+function* nestedCandidates(touchedDir: string, realCwd: string): Generator<{ file: string; dir: string; name: string }> {
+  for (const dir of nestedContextDirs(touchedDir, realCwd)) {
+    for (const name of NESTED_CONTEXT_NAMES) yield { file: path.join(dir, name), dir, name }
+  }
+}
+
+/** Everything the on-demand load needs from the session and the tool call, grouped so
+ * the per-file worker stays a three-argument function. */
+interface NestedLoadContext {
+  home: string
+  cwd: string
+  realCwd: string
+  projectRoot: string
+  excludeGlobs: string[]
+  /** The file whose access triggered the load, for trigger_file_path. */
+  touched: string
+  /** Paths already in the system prompt, so a nested @import does not repeat one. */
+  launchLoaded: string[]
+}
+
+/** One nested context file's block and the instruction loads it should announce, or
+ * nothing to attach: absent, excluded, empty, or reaching outside the project. `read`
+ * reports whether the file was there at all, so a file that exists is only ever
+ * attached once while a missing one can still appear later in the session. */
+function nestedContextBlock(file: string, dir: string, load: NestedLoadContext): { read: boolean; text?: string; events?: InstructionLoadEvent[] } {
+  if (isExcludedPath(file, load.excludeGlobs, load.home)) return { read: false }
+  // The file itself may be a link out of the project, whatever its directory is.
+  const [real] = realRoots([file])
+  if (real === undefined || !isUnder(real, [load.realCwd])) return { read: false }
+  const content = readContextFile(real)
+  if (content === undefined) return { read: false }
+  const body = stripBlockComments(content).trim()
+  if (body.length === 0) return { read: true }
+  // Its own @imports resolve at project roots, on a budget of their own: this load is
+  // outside the launch-time expansion the shared budget covers. The launch-time paths
+  // seed the seen set, so a nested file importing the root CLAUDE.md does not pay for
+  // a body already in the system prompt.
+  const seen = new Set([...load.launchLoaded, real])
+  const imports = collectImports(content, dir, load.home, rootsForImporter(real, load.home, load.cwd), seen, {
+    importer: real,
+    isExcluded: (absPath) => isExcludedPath(absPath, load.excludeGlobs, load.home),
+    budget: createImportBudget(),
+  })
+  return {
+    read: true,
+    text: [instructionsBlock(file, body), ...imports.map((entry) => `### ${entry.path}\n\n${stripBlockComments(entry.body)}`)].join('\n\n'),
+    events: [
+      { file_path: file, memory_type: memoryTypeForPath(file, load.home, load.projectRoot), load_reason: 'nested_traversal', trigger_file_path: load.touched },
+      ...imports.map((entry) => ({
+        file_path: entry.path,
+        memory_type: memoryTypeForPath(entry.path, load.home, load.projectRoot),
+        load_reason: 'include',
+        parent_file_path: file,
+      })),
+    ],
+  }
+}
+
+/** The context files Claude loads on demand rather than at launch, in the order it
+ * reads them within a directory. */
+const NESTED_CONTEXT_NAMES = ['CLAUDE.md', 'CLAUDE.local.md'] as const
+
+/** The directories between a touched file and cwd, nearest cwd first.
+ *
+ * Claude loads CLAUDE.md from cwd and every directory above it at launch, and the
+ * ones below "are included when Claude reads files in those directories"
+ * (memory.md). Only the strictly-below range belongs here; cwd's own file is
+ * already in the prompt. A file outside cwd contributes nothing.
+ */
+function nestedContextDirs(from: string, cwd: string): string[] {
+  const dirs: string[] = []
+  let current = from
+  while (current !== cwd && current !== path.dirname(current)) {
+    dirs.unshift(current)
+    current = path.dirname(current)
+  }
+  // The walk reached the filesystem root without meeting cwd, so the file is outside
+  // it: nothing below cwd to load. A file in cwd itself ends the loop with no dirs.
+  return current === cwd ? dirs : []
+}
+
+/** The context-file names pi prefers over CLAUDE.md in the same directory. Mirrors
+ * pi's own lookup order (init.ts CONTEXT_FILE_CANDIDATES); the sibling search below
+ * keys off what pi actually loaded, so this is only used to recognize those files. */
+const AGENTS_FILE_NAMES = new Set(['AGENTS.override.md', 'AGENTS.md', 'AGENTS.MD'])
+
+/** The blocks and instruction loads for one touched directory. `loaded` is the
+ * session's set of already-attached files and is updated in place, so a file that
+ * exists is attached once and a missing one can still appear later. */
+function nestedContextAttachments(touchedDir: string, load: NestedLoadContext, loaded: Set<string>, localsApproved: boolean): { bodies: string[]; events: InstructionLoadEvent[] } {
+  const bodies: string[] = []
+  const events: InstructionLoadEvent[] = []
+  for (const { file, dir, name } of nestedCandidates(touchedDir, load.realCwd)) {
+    if (loaded.has(file)) continue
+    // A CLAUDE.local.md needs a decision, never the "nothing here to gate" shortcut:
+    // the approval walk only looks at or above cwd, so this is the one door it cannot
+    // see (see isGatedFileApproved).
+    if (name === 'CLAUDE.local.md' && !localsApproved) continue
+    const block = nestedContextBlock(file, dir, load)
+    if (block.read) loaded.add(file)
+    if (block.text === undefined) continue
+    bodies.push(block.text)
+    events.push(...(block.events ?? []))
+  }
+  return { bodies, events }
+}
+
+/** The CLAUDE.md files pi passed over.
+ *
+ * Claude Code reads CLAUDE.md and never AGENTS.md, and its documented recipe for a
+ * repository that already has an AGENTS.md is a CLAUDE.md that imports it and adds
+ * Claude-specific instructions below (memory.md, "AGENTS.md"). pi loads one context
+ * file per directory and prefers AGENTS.md, so on exactly that layout the
+ * Claude-specific half never reaches the prompt. Each one found here is loaded like
+ * any other project file: exclude-checked, comment-stripped, imports expanded.
+ *
+ * The `@AGENTS.md` the recipe opens with costs nothing: pi's own file paths already
+ * seed the import seen-set, so the body it names is not injected a second time. */
+function siblingClaudeMdFiles(native: Array<{ path: string; content: string }>): Array<{ path: string; content: string }> {
+  const loaded = new Set(realRoots(native.map((file) => file.path)))
+  const found: Array<{ path: string; content: string }> = []
+  for (const file of native) {
+    if (!AGENTS_FILE_NAMES.has(path.basename(file.path))) continue
+    // CLAUDE.md only: pi also answers to CLAUDE.MD, but Claude Code reads the one
+    // spelling, and on a case-insensitive filesystem looking for both finds the same
+    // file twice under two names.
+    const candidate = path.join(path.dirname(file.path), 'CLAUDE.md')
+    const [real] = realRoots([candidate])
+    if (real !== undefined && loaded.has(real)) continue
+    const content = readContextFile(candidate)
+    if (content === undefined) continue
+    found.push({ path: candidate, content })
+  }
+  return found
+}
+
+/** The CLAUDE.md files pi passed over, appended as project_instructions blocks in the
+ * ./CLAUDE.md slot, ahead of the ./.claude/CLAUDE.md alternate and the locals. */
+function siblingClaudeMdAddition(siblings: Array<{ path: string; content: string }>, home: string, projectRoot: string, announce: (event: InstructionLoadEvent) => void): string {
+  let addition = ''
+  for (const sibling of siblings) {
+    if (sibling.content.trim().length === 0) continue
+    announce({ file_path: sibling.path, memory_type: memoryTypeForPath(sibling.path, home, projectRoot), load_reason: 'session_start' })
+    addition += `\n\n${instructionsBlock(sibling.path, sibling.content.trim())}`
+  }
+  return addition
+}
+
 /** The project-scope ./.claude/CLAUDE.md appended as a project_instructions block,
  * announced as it is added (only when non-empty, matching what reaches the prompt).
  * Claude reads project instructions from ./CLAUDE.md OR ./.claude/CLAUDE.md; pi loads
@@ -543,6 +704,19 @@ function additionalDirsAddition(extras: Array<{ path: string; content: string; d
 /** The `## Imported context (@)` section for every resolved @import, with the
  * budget-exhaustion notice, announcing each as an `include`. Empty when nothing
  * was imported. */
+/** The refusal notice: every existing file an @import named that its importer may not
+ * reach. Claude asks about these through an approval dialog and loads the ones you
+ * allow; pi-code refuses them, and this is what says so. Silence was the real defect:
+ * the importing file looks loaded and its instructions are simply not there. */
+function refusedImportsAddition(refused: Set<string>): string {
+  if (refused.size === 0) return ''
+  const list = [...refused]
+    .sort((a, b) => a.localeCompare(b, 'en'))
+    .map((file) => `- ${file}`)
+    .join('\n')
+  return `\n\n## Imports not loaded (@)\n\nThese files resolve outside what the file importing them may read, so their contents are not in context:\n\n${list}`
+}
+
 function importedAddition(imported: ImportedFile[], budget: ImportBudget, home: string, projectRoot: string, announce: (event: InstructionLoadEvent) => void): string {
   if (imported.length === 0) return ''
   const section = imported.map((entry) => `### ${entry.path}\n\n${stripBlockComments(entry.body)}`).join('\n\n')
@@ -621,9 +795,19 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
   // natively but not this one; repo-controlled, so it is approval-gated like the
   // locals and read once at session start.
   let projectDotClaude: { path: string; content: string } | undefined
+  // Whether a file that is itself the thing to gate may be read. Decided at session
+  // start like the flag below, from the session context, which is where the trust
+  // capability lives; a tool_result context carries no approval state.
+  let gatedFilesApproved = false
   // Whether project settings may contribute claudeMdExcludes; decided at session
   // start with the silent check, so no prompt fires mid-flight.
   let projectApproved = false
+  // Every context file the last turn put in the system prompt, so a nested file's
+  // @import cannot pay for a body that is already there.
+  let launchLoadedPaths: string[] = []
+  // Nested CLAUDE.md/CLAUDE.local.md files already attached this session, so a second
+  // read in the same subtree does not repeat them.
+  const nestedLoaded = new Set<string>()
   // Instruction loads already announced on the shared bus, keyed reason:path.
   // before_agent_start fires every turn, so without this a configured
   // InstructionsLoaded hook would fire once per file per turn.
@@ -668,6 +852,7 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
     memoKey: string,
     native: Array<{ path: string; content: string }>,
     contextFiles: Array<{ path: string; content: string }>,
+    siblings: Array<{ path: string; content: string }>,
     home: string,
     cwd: string,
     excluded: (absPath: string) => boolean,
@@ -680,7 +865,7 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
     // files are never re-imported and an excluded file cannot return as an import.
     // The user, project-.claude and managed-file additions join the seed too, so a
     // context file's @import cannot pull any of them in a second time.
-    const ownPaths = [...native, ...localContexts].map((file) => file.path)
+    const ownPaths = [...native, ...localContexts, ...siblings].map((file) => file.path)
     if (userContext !== undefined) ownPaths.push(userContext.path)
     if (projectDotClaude !== undefined) ownPaths.push(projectDotClaude.path)
     ownPaths.push(managedClaudeMdPath())
@@ -757,6 +942,7 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
     }
     // Read after the local-context flow so an approval it just recorded is honored.
     projectApproved = isProjectApprovedSilently(ctx)
+    gatedFilesApproved = isGatedFileApproved(ctx)
   })
 
   pi.on('before_agent_start', async (event) => {
@@ -800,33 +986,75 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
 
     const keptLocals = localContexts.filter((local) => !excluded(local.path)).map((local) => ({ path: local.path, content: stripBlockComments(local.content) }))
 
+    // Repo-controlled text, so gated on the same approval as the locals and the
+    // ./.claude/CLAUDE.md; read here rather than at session start because only the
+    // turn's contextFiles say which file pi actually chose per directory.
+    const keptSiblings = (projectApproved ? siblingClaudeMdFiles(native) : []).filter((sibling) => !excluded(sibling.path)).map((sibling) => ({ path: sibling.path, content: stripBlockComments(sibling.content) }))
+
     // ./.claude/CLAUDE.md, deduped against pi's native context so that if pi ever
     // loads it too there is no double block, then exclude-checked and comment-stripped
     // like the rest. Its @imports resolve at project roots (rootsForImporter).
     const nativeReal = new Set(realRoots(native.map((file) => file.path)))
     const [dotReal] = projectDotClaude !== undefined ? realRoots([projectDotClaude.path]) : []
-    const keptProjectDotClaude = projectDotClaude !== undefined && !(dotReal !== undefined && nativeReal.has(dotReal)) && !excluded(projectDotClaude.path) ? { path: projectDotClaude.path, content: stripBlockComments(projectDotClaude.content) } : undefined
+    const siblingReal = new Set(realRoots(keptSiblings.map((sibling) => sibling.path)))
+    const keptProjectDotClaude = projectDotClaude !== undefined && !(dotReal !== undefined && (nativeReal.has(dotReal) || siblingReal.has(dotReal))) && !excluded(projectDotClaude.path) ? { path: projectDotClaude.path, content: stripBlockComments(projectDotClaude.content) } : undefined
 
     // The user CLAUDE.md and ./.claude/CLAUDE.md join the import-expansion set so their
     // @imports resolve (each at roots scoped to it, via rootsForImporter); their own
     // bodies are placed separately, so expansion only surfaces what they import.
-    const contextFiles = [...rewrite.kept, ...(keptUser !== undefined ? [keptUser] : []), ...(keptProjectDotClaude !== undefined ? [keptProjectDotClaude] : []), ...keptLocals]
+    const contextFiles = [...rewrite.kept, ...(keptUser !== undefined ? [keptUser] : []), ...keptSiblings, ...(keptProjectDotClaude !== undefined ? [keptProjectDotClaude] : []), ...keptLocals]
 
     // Everything the expansion depends on, hashed: a turn whose inputs match the memo
     // and whose recorded mtimes are unchanged reuses the previous expansion outright.
     const addDirsRaw = additionalDirsClaudeMdEnabled() ? String(pi.getFlag?.('add-dir') ?? '') : ''
     const memoKey = buildImportMemoKey({ cwd, home, projectApproved, addDirsRaw, excludeGlobs, native, localContexts, userContext, projectDotClaude, managedFile, contextFiles })
 
-    const { extras, budget, imported } = resolveImports(memoKey, native, contextFiles, home, cwd, excluded)
+    const { extras, budget, imported } = resolveImports(memoKey, native, contextFiles, keptSiblings, home, cwd, excluded)
+    launchLoadedPaths = realRoots([...contextFiles.map((file) => file.path), ...imported.map((entry) => entry.path)])
 
     // Project memory precedes local memory, so the ./.claude/CLAUDE.md block leads the
     // additions, ahead of the CLAUDE.local.md bodies.
-    let addition = projectContextAddition(keptProjectDotClaude, home, projectRoot, announce)
+    let addition = siblingClaudeMdAddition(keptSiblings, home, projectRoot, announce)
+    addition += projectContextAddition(keptProjectDotClaude, home, projectRoot, announce)
     addition += localContextAddition(keptLocals, announce)
     addition += additionalDirsAddition(extras, announce)
     addition += importedAddition(imported, budget, home, projectRoot, announce)
+    addition += refusedImportsAddition(budget.refused)
     if (!changed && addition.length === 0) return
 
     return { systemPrompt: prompt + addition }
   })
+
+  // Claude's nested traversal: CLAUDE.md and CLAUDE.local.md below the working
+  // directory are not loaded at launch but "are included when Claude reads files in
+  // those subdirectories" (memory.md). pi's loader stops at cwd, so the whole
+  // below-cwd range is missing; this attaches each one to the tool result that
+  // touched its directory, which is the same seam claude-rules uses for a scoped
+  // rule. Once per file per session, ordered shallowest first so the deepest
+  // instructions are read last, matching the launch-time ordering.
+  pi.on('tool_result', async (event, ctx) => {
+    const rel = fileToolTarget(event)
+    if (rel === undefined) return
+    // Repo-controlled text, gated like every other project file this extension adds.
+    if (!projectApproved) return
+    // Realpath both sides: the walk below is lexical, so a symlinked subdirectory
+    // would otherwise carry it straight out of the project.
+    const [realCwd = ctx.cwd] = realRoots([ctx.cwd])
+    const touched = path.resolve(ctx.cwd, rel)
+    // The directory, not the file: a write creates its target, and a read of a path
+    // that has since moved should still contribute what its directory holds.
+    const [touchedDir] = realRoots([path.dirname(touched)])
+    if (touchedDir === undefined) return
+
+    const home = os.homedir()
+    const projectRoot = repoRoot(ctx.cwd) ?? ctx.cwd
+    const excludeGlobs = readClaudeMdExcludes(claudeMdExcludeFiles(ctx.cwd, home, projectApproved), readManagedSettings())
+    const load: NestedLoadContext = { home, cwd: ctx.cwd, realCwd, projectRoot, excludeGlobs, touched, launchLoaded: launchLoadedPaths }
+    const { bodies, events } = nestedContextAttachments(touchedDir, load, nestedLoaded, gatedFilesApproved)
+    for (const loaded of events) announce(loaded)
+    if (bodies.length === 0) return
+    // Capped like every other tool output: one read in a deep subtree must not be
+    // able to spend the context window on memory files.
+    return { content: [...event.content, { type: 'text' as const, text: capForContext(bodies.join('\n\n')) }] }
+  })
 }

package/extensions/env-settings.ts

@@ -36,15 +36,11 @@ 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 { claudeConfigDir } from './internal/config-dir.js'
 import { readManagedSettings } from './internal/managed-settings.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { claudeSettingsChain } from './internal/settings-chain.js'
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
+import { isRecord } from './internal/values.js'
 
 /** The `env` object of one settings scope, coerced to string values. A string is kept
  * as-is, a number or boolean becomes its String() form, and anything else (object,

package/extensions/git-checkpoint.ts

@@ -19,6 +19,7 @@ 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'
+import { contentText, errorMessage } from './internal/values.js'
 
 const CUSTOM_TYPE = 'git-checkpoint'
 /** Sidecar inside the bare shadow repo recording the work tree it snapshots. */
@@ -116,17 +117,8 @@ function rememberWorkTree(shadowDir: string, cwd: string): void {
   }
 }
 
-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(' ')
-}
-
 function promptSnippet(content: unknown): string {
-  const text = extractText(content).replace(/\s+/g, ' ').trim()
+  const text = contentText(content, ' ').replace(/\s+/g, ' ').trim()
   if (text.length <= PROMPT_SNIPPET_LENGTH) return text
   return `${text.slice(0, PROMPT_SNIPPET_LENGTH)}…`
 }
@@ -156,7 +148,7 @@ async function restoreConversation(ctx: ExtensionCommandContext, entryId: string
     if (typeof result.editorText === 'string') ctx.ui.setEditorText(result.editorText)
     return true
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
+    const message = errorMessage(error)
     ctx.ui.notify(`Conversation restore failed: ${message}`, 'error')
     return false
   }
@@ -237,7 +229,7 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
     } 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')
+      ctx.ui.notify(`Checkpoints cannot honor this repository's .git/info/exclude: ${errorMessage(error)}`, 'warning')
     }
   }
 

package/extensions/goal.ts

@@ -37,7 +37,6 @@
 
 import * as os from 'node:os'
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
-
 import { hookFiles, readSettingsDisableAllHooks, stopHookBlockCap } from './hooks/index.js'
 import {
   checkinIntervalMs,
@@ -66,6 +65,7 @@ import { completeText } from './internal/model-complete.js'
 import { resolveModelOverride } from './internal/model-lookup.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { isSubagentPhaseEvent, SUBAGENT_CHANNEL } from './internal/subagent-events.js'
+import { errorMessage } from './internal/values.js'
 
 /** Session entry type the goal state persists under, and the custom message type its
  * transcript lines (kickoff, verdicts, check-ins) carry. */
@@ -340,7 +340,7 @@ export default function goalExtension(pi: ExtensionAPI) {
       // A user interrupt is not an evaluator failure: the goal stays, nothing to say.
       if (ctx.signal?.aborted) return
       // No verdict is a hook error in Claude's terms: the turn ends and the goal stays.
-      if (generation === startedGeneration) tell(ctx, `Goal evaluator error: ${error instanceof Error ? error.message : String(error)}. The goal stays set; the next turn is evaluated again.`, 'warning')
+      if (generation === startedGeneration) tell(ctx, `Goal evaluator error: ${errorMessage(error)}. The goal stays set; the next turn is evaluated again.`, 'warning')
       return
     }
     // Interrupted, cleared, or replaced during the await: this verdict must not act.

package/extensions/hooks/config.ts

@@ -8,7 +8,8 @@ import * as fs from 'node:fs'
 import * as path from 'node:path'
 import { readManagedSettings } from '../internal/managed-settings.js'
 import { type InstalledPlugin, pluginComponentPath, substitutePluginVars } from '../internal/plugins.js'
-import { claudeSettingsChain } from '../internal/settings-chain.js'
+import { claudeSettingsChain, readSettingsChain } from '../internal/settings-chain.js'
+import { errorMessage, isRecord } from '../internal/values.js'
 
 export interface HookCommand {
   type?: string
@@ -67,10 +68,6 @@ export function isBackgroundHook(hook: HookCommand): boolean {
 }
 export type HooksConfig = Record<string, HookMatcher[]>
 
-export function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
 /** 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. */
@@ -92,13 +89,8 @@ export function readDisableAllHooks(files: string[], managed: Record<string, unk
  * disableAllHooks cannot disable hooks configured through managed policy settings,
  * so the caller keeps managed hooks running when only this half is set. */
 export function readSettingsDisableAllHooks(files: string[]): boolean {
-  for (const file of files) {
-    try {
-      const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'))
-      if (isRecord(parsed) && parsed.disableAllHooks === true) return true
-    } catch {
-      // missing or invalid file: skip
-    }
+  for (const settings of readSettingsChain(files)) {
+    if (settings.disableAllHooks === true) return true
   }
   return false
 }
@@ -152,14 +144,7 @@ export function readAllowedHttpHookUrls(files: string[], managed: Record<string,
     found = [...(found ?? []), ...value.filter((entry): entry is string => typeof entry === 'string')]
   }
   collect(managed.allowedHttpHookUrls)
-  for (const file of files) {
-    try {
-      const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'))
-      if (isRecord(parsed)) collect(parsed.allowedHttpHookUrls)
-    } catch {
-      // missing or invalid file: skip
-    }
-  }
+  for (const settings of readSettingsChain(files)) collect(settings.allowedHttpHookUrls)
   return found
 }
 
@@ -203,7 +188,7 @@ function mergeHooksJson(config: HooksConfig, raw: string, source: string, source
   } catch (error) {
     // Every hook this source declares is now absent, a policy hook among them, so the
     // failure is named rather than left to look like a file with no hooks in it.
-    console.warn(`pi-code-hooks: ignoring the hooks in ${source}: ${error instanceof Error ? error.message : String(error)}`)
+    console.warn(`pi-code-hooks: ignoring the hooks in ${source}: ${errorMessage(error)}`)
     return
   }
   for (const [event, matchers] of Object.entries(parsed?.hooks ?? {})) {

package/extensions/hooks/decisions.ts

@@ -6,8 +6,9 @@
 
 import type { ToolCallEventResult } from '@earendil-works/pi-coding-agent'
 import type { PathAnchors } from '../internal/path-rules.js'
+import { errorMessage, isRecord } from '../internal/values.js'
 import { claudeToolInput, claudeToolName, piToolInput } from './claude-tools.js'
-import { type HookCommand, type HooksConfig, isRecord } from './config.js'
+import type { HookCommand, HooksConfig } from './config.js'
 import { allCommands, matchingCommands, passesIfFilter } from './matcher.js'
 import { type HookRunner, type HookRunResult, timeoutMs } from './runners.js'
 
@@ -63,7 +64,7 @@ export function hookJsonError(text: string): string | undefined {
     JSON.parse(trimmed)
     return undefined
   } catch (error) {
-    parseError = error instanceof Error ? error.message : String(error)
+    parseError = errorMessage(error)
   }
   const lines = trimmed
     .split('\n')