pi-code 1.0.57 → 1.0.59

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/context-imports.ts

@@ -67,18 +67,20 @@ import { createHash } from 'node:crypto'
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
-
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { claudeConfigDir } from './internal/config-dir.js'
+import { AGENTS_FILE_NAMES } from './internal/context-files.js'
+import { externalImportDecision, externalImportKey, rememberExternalImportDecision } from './internal/external-imports.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, 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
@@ -106,8 +108,13 @@ export function expandHome(target: string, home: string): string {
   return target
 }
 
+/** Stands for "no boundary" in an allowed-roots list: the grant a project gets when
+ * its external imports are approved, where a file may import from anywhere as Claude's
+ * dialog allows. A real path never equals it, and realRoots never produces it. */
+const ANY_ROOT = '*'
+
 function isUnder(target: string, roots: string[]): boolean {
-  return roots.some((root) => target === root || target.startsWith(root + path.sep))
+  return roots.some((root) => root === ANY_ROOT || target === root || target.startsWith(root + path.sep))
 }
 
 /** Realpath the roots that exist; used both to seed and to bound the import search. */
@@ -138,9 +145,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 +172,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 +204,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 +243,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
@@ -252,11 +277,16 @@ export function collectImports(content: string, fromDir: string, home: string, a
  * project's transcripts, so granting those roots to a cloned repo's `CLAUDE.md`
  * would let it read them into the system prompt.
  */
-export function rootsForImporter(importer: string, home: string, cwd: string): string[] {
+export function rootsForImporter(importer: string, home: string, cwd: string, externalApproved = false): string[] {
   const userRoots = realRoots([claudeConfigDir(home), path.join(home, '.pi')])
   const [real] = realRoots([importer])
   const fromUserConfig = real !== undefined && isUnder(real, userRoots)
   if (fromUserConfig) return realRoots([cwd, ...userRoots])
+  // The project was asked about its external imports and allowed them, so a project
+  // file may reach outside, as Claude's dialog grants. The widening is deliberately
+  // only for project files: a user-scope file's roots are its own config, and an
+  // approval given to a repository must not extend them.
+  if (externalApproved) return [ANY_ROOT]
   // A non-config file is bounded at the repository root: that covers an ancestor
   // context file (a repo-root CLAUDE.md or CLAUDE.local.md in a subdirectory
   // session, where cwd alone silently dropped its relative imports) without
@@ -479,24 +509,205 @@ function additionalDirExtras(addDirs: string[], seenSet: Set<string>, excluded:
   return extras
 }
 
+/** The parts of one launch-time expansion that every file shares: where it runs, what
+ * has already been read, the budget they all draw on, and whether this project's
+ * external imports were approved. */
+interface ExpansionContext {
+  home: string
+  cwd: string
+  seen: Set<string>
+  excluded: (absPath: string) => boolean
+  budget: ImportBudget
+  externalApproved: boolean
+}
+
 /** Resolve every context and additional-dir file's @imports through the one shared
  * budget, each with roots scoped to the importing file so a project file never
- * reaches user config. */
-function expandImports(contextFiles: Array<{ path: string; content: string }>, extras: Array<{ path: string; content: string; dir: string }>, home: string, cwd: string, seenSet: Set<string>, excluded: (absPath: string) => boolean, budget: ImportBudget): ImportedFile[] {
+ * reaches user config unless the project's external imports were approved. */
+function expandImports(contextFiles: Array<{ path: string; content: string }>, extras: Array<{ path: string; content: string; dir: string }>, run: ExpansionContext): ImportedFile[] {
   const imported: ImportedFile[] = []
+  const options = { budget: run.budget, isExcluded: run.excluded }
   for (const file of contextFiles) {
-    const allowedRoots = rootsForImporter(file.path, home, cwd)
-    imported.push(...collectImports(file.content, path.dirname(file.path), home, allowedRoots, seenSet, { budget, importer: file.path, isExcluded: excluded }))
+    const allowedRoots = rootsForImporter(file.path, run.home, run.cwd, run.externalApproved)
+    imported.push(...collectImports(file.content, path.dirname(file.path), run.home, allowedRoots, run.seen, { ...options, importer: file.path }))
   }
   for (const extra of extras) {
     // The additional dir itself is an allowed root, so its files' relative imports
     // resolve even from .claude/rules two levels down.
-    const allowedRoots = [...realRoots([extra.dir]), ...rootsForImporter(extra.path, home, cwd)]
-    imported.push(...collectImports(extra.content, path.dirname(extra.path), home, allowedRoots, seenSet, { budget, importer: extra.path, isExcluded: excluded }))
+    const allowedRoots = [...realRoots([extra.dir]), ...rootsForImporter(extra.path, run.home, run.cwd)]
+    imported.push(...collectImports(extra.content, path.dirname(extra.path), run.home, allowedRoots, run.seen, { ...options, importer: extra.path }))
   }
   return imported
 }
 
+/** The external-import dialog's title. Exported so a test can tell it apart from the
+ * project-trust dialog by identity rather than by matching a prefix that a retitle
+ * would silently break. */
+export const EXTERNAL_IMPORT_PROMPT_TITLE = 'Load imports from outside this project?'
+
+/** Ask about the imports the expansion just refused for leaving the project.
+ *
+ * The list is the refusals the enforcing path produced, not a second enumeration of
+ * what it might refuse: same files, same depth, same resolution, same exclusions. That
+ * is the only way the dialog can promise it names everything the approval lets in.
+ */
+async function askExternalImports(ctx: ExtensionContext, root: string, refused: ReadonlySet<string>): Promise<boolean> {
+  const listed = [...refused]
+    .sort((a, b) => a.localeCompare(b, 'en'))
+    .map((file) => `  ${file}`)
+    .join('\n')
+  const body = `${root}\n\nIts context files import these files from outside the project:\n\n${listed}\n\nThey will be read into every session's context. Only allow this for repositories you trust.`
+  return await ctx.ui.confirm(EXTERNAL_IMPORT_PROMPT_TITLE, body)
+}
+
+/** 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 budget = createImportBudget()
+  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,
+  })
+  return {
+    read: true,
+    // The refusal notice rides along, so an import this file names and does not get is
+    // as visible here as it is at launch.
+    text: [instructionsBlock(file, body), ...imports.map((entry) => `### ${entry.path}\n\n${stripBlockComments(entry.body)}`)].join('\n\n') + refusedImportsAddition(budget.refused),
+    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 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
@@ -535,6 +746,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')
@@ -584,6 +808,7 @@ function buildImportMemoKey(input: {
   cwd: string
   home: string
   projectApproved: boolean
+  externalApproved: boolean
   addDirsRaw: string
   excludeGlobs: string[]
   native: Array<{ path: string; content: string }>
@@ -594,7 +819,7 @@ function buildImportMemoKey(input: {
   contextFiles: Array<{ path: string; content: string }>
 }): string {
   const keyHash = createHash('sha256')
-  keyHash.update(`${input.cwd}\0${input.home}\0${input.projectApproved}\0${input.addDirsRaw}\0${input.excludeGlobs.join(',')}\0`)
+  keyHash.update(`${input.cwd}\0${input.home}\0${input.projectApproved}\0${input.externalApproved}\0${input.addDirsRaw}\0${input.excludeGlobs.join(',')}\0`)
   for (const file of [...input.native, ...input.localContexts]) keyHash.update(`${file.path}\0`)
   if (input.userContext !== undefined) keyHash.update(`${input.userContext.path}\0`)
   if (input.projectDotClaude !== undefined) keyHash.update(`${input.projectDotClaude.path}\0`)
@@ -613,9 +838,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.
@@ -658,11 +893,8 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
   // set) is rebuilt for next turn.
   const resolveImports = (
     memoKey: string,
-    native: Array<{ path: string; content: string }>,
-    contextFiles: Array<{ path: string; content: string }>,
-    home: string,
-    cwd: string,
-    excluded: (absPath: string) => boolean,
+    files: { native: Array<{ path: string; content: string }>; context: Array<{ path: string; content: string }>; siblings: Array<{ path: string; content: string }> },
+    run: { home: string; cwd: string; excluded: (absPath: string) => boolean; externalApproved: boolean },
   ): { extras: Array<{ path: string; content: string; dir: string }>; budget: ImportBudget; imported: ImportedFile[] } => {
     if (importMemo?.key === memoKey && memoIsFresh(importMemo)) {
       const { extras, budget, imported } = importMemo
@@ -672,7 +904,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 = [...files.native, ...localContexts, ...files.siblings].map((file) => file.path)
     if (userContext !== undefined) ownPaths.push(userContext.path)
     if (projectDotClaude !== undefined) ownPaths.push(projectDotClaude.path)
     ownPaths.push(managedClaudeMdPath())
@@ -681,14 +913,14 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
     // Claude's --add-dir memory loading, env-gated. The files join the seen set
     // before import expansion so an @import cannot pull one in twice, and they get
     // the same exclude and comment-strip treatment as native context files.
-    const addDirs = additionalDirsClaudeMdEnabled() ? parseAdditionalDirs(pi.getFlag?.('add-dir'), home, cwd) : []
-    const extras = additionalDirExtras(addDirs, seenSet, excluded, projectApproved)
+    const addDirs = additionalDirsClaudeMdEnabled() ? parseAdditionalDirs(pi.getFlag?.('add-dir'), run.home, run.cwd) : []
+    const extras = additionalDirExtras(addDirs, seenSet, run.excluded, projectApproved)
 
     // One budget for the whole run, so N context files cannot each spend a full one.
     // Exclusion applies inside the recursion: an excluded @import is skipped before
     // it is read, so its transitive imports never load and it spends no budget.
     const budget = createImportBudget()
-    const imported = expandImports(contextFiles, extras, home, cwd, seenSet, excluded, budget)
+    const imported = expandImports(files.context, extras, { ...run, seen: seenSet, budget })
 
     // Revalidation set: every file the expansion read, plus each add-dir itself
     // (a directory's mtime moves when a memory file is added or removed there).
@@ -749,9 +981,30 @@ 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) => {
+  /** The launch-time expansion, asking about what it refuses for leaving the project
+   * when this project has not been asked yet.
+   *
+   * Claude asks once per project and remembers the answer either way. The list is what
+   * this very expansion refused, so it names exactly the files the answer governs, and
+   * on approval the expansion is simply redone with the wider roots. */
+  const expandAskingAboutExternals = async (
+    cwd: string,
+    ctx: ExtensionContext | undefined,
+    expandWith: (externalApproved: boolean) => { extras: Array<{ path: string; content: string; dir: string }>; budget: ImportBudget; imported: ImportedFile[] },
+  ): Promise<{ extras: Array<{ path: string; content: string; dir: string }>; budget: ImportBudget; imported: ImportedFile[] }> => {
+    const key = externalImportKey(cwd)
+    const decided = externalImportDecision(key)
+    const result = expandWith(decided === true)
+    if (decided !== null || result.budget.refused.size === 0 || ctx?.hasUI !== true) return result
+    const approved = await askExternalImports(ctx, key, result.budget.refused)
+    rememberExternalImportDecision(key, approved)
+    return approved ? expandWith(true) : result
+  }
+
+  pi.on('before_agent_start', async (event, ctx) => {
     const home = os.homedir()
     const cwd = event.systemPromptOptions?.cwd ?? process.cwd()
     const native: Array<{ path: string; content: string }> = event.systemPromptOptions?.contextFiles ?? []
@@ -792,33 +1045,82 @@ 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 expandWith = (externalApproved: boolean) => {
+      const memoKey = buildImportMemoKey({ cwd, home, projectApproved, externalApproved, addDirsRaw, excludeGlobs, native, localContexts, userContext, projectDotClaude, managedFile, contextFiles })
+      return resolveImports(memoKey, { native, context: contextFiles, siblings: keptSiblings }, { home, cwd, excluded, externalApproved })
+    }
 
-    const { extras, budget, imported } = resolveImports(memoKey, native, contextFiles, home, cwd, excluded)
+    // Claude's external-import dialog. Asked from the refusals the expansion just
+    // produced, so the files named are exactly the files the answer governs, and asked
+    // here rather than at session start because only this event knows which context
+    // files pi actually loaded. Once per project: the answer is remembered either way.
+    const { extras, budget, imported } = await expandAskingAboutExternals(cwd, ctx, expandWith)
+    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/init.ts

@@ -16,13 +16,15 @@
 
 import * as fs from 'node:fs'
 import * as path from 'node:path'
+
+import { CONTEXT_FILE_CANDIDATES } from './internal/context-files.js'
+
+export { CONTEXT_FILE_CANDIDATES }
+
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
 import { repoRoot } from './internal/project-root.js'
 
-/** Context files pi recognizes, in its lookup order; the first hit wins. */
-export const CONTEXT_FILE_CANDIDATES = ['AGENTS.override.md', 'AGENTS.md', 'AGENTS.MD', 'CLAUDE.md', 'CLAUDE.MD']
-
 function statOf(target: string): fs.Stats | undefined {
   try {
     return fs.statSync(target)

package/extensions/internal/context-files.ts

@@ -0,0 +1,14 @@
+/**
+ * The context-file names pi looks for, in its own lookup order.
+ *
+ * Mirrors pi's resource loader: it takes the first of these that exists in a
+ * directory and ignores the rest, so a repository holding both AGENTS.md and
+ * CLAUDE.md loads only the first. Anything reasoning about what pi loaded, or about
+ * what it passed over, has to use the same list in the same order.
+ */
+
+/** pi's per-directory candidates, first hit wins. */
+export const CONTEXT_FILE_CANDIDATES = ['AGENTS.override.md', 'AGENTS.md', 'AGENTS.MD', 'CLAUDE.md', 'CLAUDE.MD']
+
+/** The candidates pi prefers over CLAUDE.md in the same directory. */
+export const AGENTS_FILE_NAMES: ReadonlySet<string> = new Set(['AGENTS.override.md', 'AGENTS.md', 'AGENTS.MD'])

package/extensions/internal/external-imports.ts

@@ -0,0 +1,74 @@
+/**
+ * Whether a project may load `@imports` that resolve outside it.
+ *
+ * Claude Code asks once per project, listing the external files, and remembers the
+ * answer: "The first time Claude Code encounters external imports in a project, it
+ * shows an approval dialog listing the files. If you decline, the imports stay
+ * disabled and the dialog doesn't appear again."
+ *
+ * The answer lives beside pi's own trust store rather than in the repository, so a
+ * clone cannot ship its own approval. It is keyed on the checkout: the resolved git
+ * root, or the resolved working directory outside a repository.
+ *
+ * The key is the git root and not the project root because a repository must not be
+ * able to move its own key. The project root also stops at package.json, so declining
+ * at the top of a monorepo and starting the next session inside a package produced a
+ * different key and asked again, which is not a decision that was kept. A separate
+ * worktree of one repository is a separate checkout and is asked separately.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
+
+import { atomicWriteFile } from './atomic-write.js'
+import { gitRoot } from './project-root.js'
+import { isRecord } from './values.js'
+
+/** The key for a working directory: its checkout, resolved, so the same checkout
+ * reached through a symlink is the same project. */
+export function externalImportKey(cwd: string): string {
+  const root = gitRoot(cwd) ?? cwd
+  try {
+    return fs.realpathSync(root)
+  } catch {
+    return root
+  }
+}
+
+/** The store file. A seam: the tests point it at a temp directory. */
+export function externalImportStorePath(agentDir: string = getAgentDir()): string {
+  return path.join(agentDir, 'pi-code-external-imports.json')
+}
+
+function readStore(storePath: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(storePath, 'utf-8'))
+    return isRecord(parsed) ? parsed : {}
+  } catch {
+    // No store yet, or one a hand-edit left unparseable: no decision recorded.
+    return {}
+  }
+}
+
+/** The recorded answer for `root`, or null when the project has never been asked.
+ * Only a boolean counts: anything else in the file reads as unasked, so a corrupt
+ * entry re-asks rather than silently allowing or silently refusing forever. */
+export function externalImportDecision(root: string, storePath: string = externalImportStorePath()): boolean | null {
+  const value = readStore(storePath)[root]
+  return typeof value === 'boolean' ? value : null
+}
+
+/** Record the answer for `root`, keeping every other project's. */
+export function rememberExternalImportDecision(root: string, allowed: boolean, storePath: string = externalImportStorePath()): void {
+  const store = readStore(storePath)
+  store[root] = allowed
+  try {
+    fs.mkdirSync(path.dirname(storePath), { recursive: true })
+    atomicWriteFile(storePath, `${JSON.stringify(store, null, 2)}\n`)
+  } catch {
+    // An unwritable agent directory costs the memory of the answer, not the session:
+    // the next start asks again, which is the safe direction.
+  }
+}

package/extensions/internal/project-approval.ts

@@ -131,6 +131,20 @@ export function isProjectApprovedSilently(ctx: Pick<ApprovalContext, 'cwd' | 'is
   return deps.savedDecision(ctx.cwd) === true
 }
 
+/**
+ * The approval decision for a file that is itself the thing to gate.
+ *
+ * The silent check short-circuits to approved when the repository holds no
+ * Claude-shaped config, meaning there is nothing here pi-code would act on. That is
+ * wrong for a file the CLAUDE_SHAPED walk cannot see: the walk only looks at or above
+ * cwd, so a CLAUDE.local.md in a subdirectory would come in through the one door the
+ * gate does not cover. Forcing the shaped answer makes such a file need a real
+ * decision, never the shortcut.
+ */
+export function isGatedFileApproved(ctx: Pick<ApprovalContext, 'cwd' | 'isProjectTrusted'> & { ui?: ApprovalContext['ui'] }, deps: ApprovalDeps = defaultDeps): boolean {
+  return isProjectApprovedSilently(ctx, { ...deps, hasClaudeShaped: () => true })
+}
+
 export async function isProjectApproved(ctx: ApprovalContext, deps: ApprovalDeps = defaultDeps): Promise<boolean> {
   if (runtimeLacksProjectTrust(ctx)) return false // pi predates project-trust support
   if (ctx.isProjectTrusted?.() !== true) return false // pi declined trust for this project

package/extensions/internal/project-root.ts

@@ -27,6 +27,24 @@ export function repoRoot(from: string): string | undefined {
   }
 }
 
+/** The git checkout at or above `from`, or undefined outside one.
+ *
+ * Narrower than repoRoot on purpose, and used where a key must be stable rather than
+ * merely near: repoRoot also stops at package.json, which every package of a monorepo
+ * ships, so a decision keyed on it changes the moment the session starts one directory
+ * deeper. `.git` cannot be committed into a repository, so it is not a marker the
+ * repository can add to move its own key.
+ */
+export function gitRoot(from: string): string | undefined {
+  let currentDir = from
+  while (true) {
+    if (fs.existsSync(path.join(currentDir, '.git'))) return currentDir
+    const parentDir = path.dirname(currentDir)
+    if (parentDir === currentDir) return undefined
+    currentDir = parentDir
+  }
+}
+
 function statOf(target: string): fs.Stats | null {
   try {
     return fs.statSync(target)

package/extensions/internal/tool-target.ts

@@ -0,0 +1,23 @@
+/**
+ * Which file a tool call touched.
+ *
+ * Two extensions attach instruction files when a file tool touches a path they cover
+ * (claude-rules for a path-scoped rule, context-imports for a nested CLAUDE.md), and
+ * both got the same detail wrong: pi's edit and write tools accept `file_path` as an
+ * alias for `path`, so a handler reading only `path` did nothing for a model that used
+ * the alias. One reader, one place to be wrong.
+ */
+
+/** The tools that name a file pi-code acts on. */
+const FILE_TOOLS: ReadonlySet<string> = new Set(['read', 'edit', 'write'])
+
+/** The path a file tool call named, or undefined for any other tool, an errored call,
+ * or a call that named none. The path is as the tool gave it: callers resolve it
+ * against their own cwd. */
+export function fileToolTarget(event: { toolName: string; input?: unknown; isError?: boolean }): string | undefined {
+  if (event.isError === true) return undefined
+  if (!FILE_TOOLS.has(event.toolName)) return undefined
+  const input = event.input as { path?: unknown; file_path?: unknown } | undefined
+  const target = typeof input?.path === 'string' ? input.path : input?.file_path
+  return typeof target === 'string' && target.length > 0 ? target : undefined
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "1.0.57",
+  "version": "1.0.59",
   "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",