pi-code 1.0.8 → 1.0.10

package/extensions/context-imports.ts

@@ -10,14 +10,23 @@
  * imported content plus the approval-gated CLAUDE.local.md body. The base
  * files pi already injected are never re-appended.
  *
+ * It also loads the Claude Code memory locations pi's own loader misses, each
+ * through the same exclude/strip/announce/import pipeline: the user-scope
+ * ~/.claude/CLAUDE.md (the user's own file, no approval gate, @imports at
+ * user-config roots), the project-scope alternate ./.claude/CLAUDE.md (nearest at
+ * or above cwd, approval-gated, deduped against pi's native blocks, @imports at
+ * project roots), and the enterprise managed CLAUDE.md file deployed beside
+ * managed-settings.json.
+ *
  * It also rewrites the context blocks pi assembled, by exact-substring
  * replacement of the wrapper reconstructed from each file's path+content (a
- * wrapper that is not found is skipped, never guessed at): a managed-settings
- * `claudeMd` block is prepended at the top of <project_context> (managed
- * settings only; the key is ignored elsewhere and the block is never
- * excludable), files matching the merged `claudeMdExcludes` globs are removed
- * along with their imports, and block-level HTML comments are stripped from
- * every surviving body (see internal/strip-comments).
+ * wrapper that is not found is skipped, never guessed at): the managed claudeMd
+ * (the managed CLAUDE.md file first, then the managed-settings `claudeMd` key)
+ * and the user CLAUDE.md are prepended at the top of <project_context> in Claude's
+ * order (managed, user, then pi's native project blocks; managed is managed-source
+ * only and never excludable), files matching the merged `claudeMdExcludes` globs
+ * are removed along with their imports, and block-level HTML comments are stripped
+ * from every surviving body (see internal/strip-comments).
  *
  * Security: context files can come from an untrusted project, so imports are
  * confined (after resolving symlinks) to the working directory plus its
@@ -43,22 +52,26 @@
  *
  * Loads are also announced on the shared instruction-events bus for the
  * InstructionsLoaded hook: `include` for each resolved @import, `session_start`
- * for the native context files that survived claudeMdExcludes plus
- * CLAUDE.local.md and additional-dir files, once per file per session. This
- * extension owns exclusion, so it owns the announcements too: a file the
- * exclusion removed never announces, and the hooks extension only consumes the
- * bus (emit is synchronous, so extension order does not matter).
+ * for the native context files that survived claudeMdExcludes plus CLAUDE.local.md,
+ * the user (User) and project ./.claude/CLAUDE.md (Project), the managed file
+ * (Managed) and additional-dir files, once per file per session. This extension
+ * owns exclusion, so it owns the announcements too: a file the exclusion removed
+ * never announces, and the hooks extension only consumes the bus (emit is
+ * synchronous, so extension order does not matter). The managed-settings `claudeMd`
+ * key is not a file pi loaded, so like today it is inserted but not announced.
  *
  * Docs: https://code.claude.com/docs/en/memory.md (imports)
  */
 
+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 { claudeConfigDir } from './internal/config-dir.js'
 import { type InstructionLoadEvent, memoryTypeForPath, publishInstructionLoad } from './internal/instruction-events.js'
-import { readManagedSettings } from './internal/managed-settings.js'
+import { managedSettingsPath, readManagedSettings } from './internal/managed-settings.js'
 import { globToRegExpSource } from './internal/path-rules.js'
 import { isProjectApproved, isProjectApprovedSilently } from './internal/project-approval.js'
 import { ancestorFiles, findNearestFile, repoRoot } from './internal/project-root.js'
@@ -222,7 +235,7 @@ export function collectImports(content: string, fromDir: string, home: string, a
  * would let it read them into the system prompt.
  */
 export function rootsForImporter(importer: string, home: string, cwd: string): string[] {
-  const userRoots = realRoots([path.join(home, '.claude'), path.join(home, '.pi')])
+  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])
@@ -286,9 +299,34 @@ export function additionalDirContextFiles(dir: string, includeLocal: boolean): A
   return files
 }
 
-/** Path label given to the managed claudeMd block; not a file pi loaded. */
+/** Path label given to the managed claudeMd settings-key block; not a file pi loaded. */
 export const MANAGED_CLAUDE_MD_PATH = 'managed-settings.json (claudeMd)'
 
+let managedClaudeMdPathOverride: string | undefined
+
+/** Test seam mirroring setManagedSettingsPath: point the managed CLAUDE.md file
+ * readers consult at a writable directory. */
+export function setManagedClaudeMdPath(file?: string): void {
+  managedClaudeMdPathOverride = file
+}
+
+/** The managed CLAUDE.md file path: alongside managed-settings.json, in the same OS
+ * directory IT deploys the enterprise policy to (managed-settings.ts owns that
+ * directory per platform). Organizations ship a CLAUDE.md there to load before user
+ * and project context. Overridable for tests. */
+export function managedClaudeMdPath(): string {
+  return managedClaudeMdPathOverride ?? path.join(path.dirname(managedSettingsPath()), 'CLAUDE.md')
+}
+
+/** The managed CLAUDE.md file body, or '' when absent or unreadable. */
+export function readManagedClaudeMdFile(): string {
+  try {
+    return fs.readFileSync(managedClaudeMdPath(), 'utf-8')
+  } catch {
+    return ''
+  }
+}
+
 /** pi's exact per-file wrapper inside <project_context>, reconstructed from
  * path+content for exact-substring rewriting. tests/context-imports.test.ts pins
  * this format against pi's own source so drift fails loudly instead of silently
@@ -317,10 +355,12 @@ function replaceBlock(prompt: string, wrapper: string, replacement: string): str
   return prompt.slice(0, at) + replacement + prompt.slice(at + wrapper.length)
 }
 
-/** Insert the managed claudeMd block at the top of <project_context>, before the
- * files pi loaded (Claude documents managed claudeMd loading before user and
- * project CLAUDE.md); when pi assembled no context block, add one in pi's shape. */
-function withManagedBlock(prompt: string, block: string): string {
+/** Insert a block at the top of <project_context>, before the files pi loaded;
+ * when pi assembled no context block, add one in pi's shape. Used for the blocks
+ * Claude loads ahead of pi's native project context: managed claudeMd (file then
+ * key) and the user CLAUDE.md. Each call prepends, so the last block inserted ends
+ * up highest, which is how the managed/user/native order is built (see caller). */
+function withTopBlock(prompt: string, block: string): string {
   for (const anchor of [CONTEXT_OPENER, '<project_context>\n\n']) {
     const at = prompt.indexOf(anchor)
     if (at === -1) continue
@@ -335,7 +375,7 @@ function withManagedBlock(prompt: string, block: string): string {
  * settings.local.json (nearest at or above cwd) only when the project is
  * approved. Managed settings are read separately by the caller. */
 export function claudeMdExcludeFiles(cwd: string, home: string, approved: boolean): string[] {
-  const files = [path.join(home, '.claude', 'settings.json')]
+  const files = [path.join(claudeConfigDir(home), 'settings.json')]
   if (!approved) return files
   for (const name of ['settings.json', 'settings.local.json']) {
     files.push(findNearestFile(cwd, path.join('.claude', name)) ?? path.join(cwd, '.claude', name))
@@ -453,6 +493,16 @@ function expandImports(contextFiles: Array<{ path: string; content: string }>, e
   return imported
 }
 
+/** 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
+ * the former natively, so this fills the alternate location as an extra project block. */
+function projectContextAddition(kept: { path: string; content: string } | undefined, home: string, projectRoot: string, announce: (event: InstructionLoadEvent) => void): string {
+  if (kept === undefined || kept.content.trim().length === 0) return ''
+  announce({ file_path: kept.path, memory_type: memoryTypeForPath(kept.path, home, projectRoot), load_reason: 'session_start' })
+  return `\n\n${instructionsBlock(kept.path, kept.content.trim())}`
+}
+
 /** The CLAUDE.local.md bodies appended after the native context, announced as they
  * are added (only the non-empty ones, matching what actually reaches the prompt). */
 function localContextAddition(keptLocals: Array<{ path: string; content: string }>, announce: (event: InstructionLoadEvent) => void): string {
@@ -491,8 +541,74 @@ function importedAddition(imported: ImportedFile[], budget: ImportBudget, home:
   return `\n\n## Imported context (@)\n\n${section}${notice}`
 }
 
+/** Prepend the managed and user memory blocks Claude loads ahead of pi's native project
+ * context, top to bottom: managed file, managed key, then the user CLAUDE.md. withTopBlock
+ * prepends, so they are inserted bottom-up (user, then managed key, then managed file just
+ * below) to land in that order. keptUser was already exclude-checked and comment-stripped by
+ * the caller like every other file; the managed claudeMd is never excludable and comes from
+ * two managed-only surfaces, the settings key (ignored in user/project settings) and the file
+ * IT deploys beside managed-settings.json, re-read every turn so a policy change applies
+ * immediately (only its announce is deduped per session). Returns the grown prompt, whether
+ * anything was added, and the managed file body (reused for the import memo key). */
+function prependMemoryBlocks(prompt: string, changed: boolean, keptUser: { path: string; content: string } | undefined, managed: Record<string, unknown>, announce: (event: InstructionLoadEvent) => void): { prompt: string; changed: boolean; managedFile: string } {
+  if (keptUser !== undefined && keptUser.content.trim().length > 0) {
+    prompt = withTopBlock(prompt, instructionsBlock(keptUser.path, keptUser.content.trim()))
+    changed = true
+    announce({ file_path: keptUser.path, memory_type: 'User', load_reason: 'session_start' })
+  }
+  const managedKey = typeof managed.claudeMd === 'string' ? stripBlockComments(managed.claudeMd).trim() : ''
+  if (managedKey.length > 0) {
+    prompt = withTopBlock(prompt, instructionsBlock(MANAGED_CLAUDE_MD_PATH, managedKey))
+    changed = true
+  }
+  const managedFile = stripBlockComments(readManagedClaudeMdFile()).trim()
+  if (managedFile.length > 0) {
+    prompt = withTopBlock(prompt, instructionsBlock(managedClaudeMdPath(), managedFile))
+    changed = true
+    announce({ file_path: managedClaudeMdPath(), memory_type: 'Managed', load_reason: 'session_start' })
+  }
+  return { prompt, changed, managedFile }
+}
+
+/** Everything the import expansion depends on, hashed to a memo key: a turn whose inputs
+ * match a prior key and whose recorded mtimes are unchanged reuses the previous expansion
+ * outright. The native/local paths, the user/project-.claude additions, and the managed file
+ * body seed the "seen" set, so a change in which of them exist (even an excluded one that
+ * never reaches contextFiles) changes the key; the managed file is re-read every turn, so a
+ * change in its content re-expands and keeps the seed self-consistent. */
+function buildImportMemoKey(input: {
+  cwd: string
+  home: string
+  projectApproved: boolean
+  addDirsRaw: string
+  excludeGlobs: string[]
+  native: Array<{ path: string; content: string }>
+  localContexts: Array<{ path: string; content: string }>
+  userContext: { path: string; content: string } | undefined
+  projectDotClaude: { path: string; content: string } | undefined
+  managedFile: string
+  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`)
+  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`)
+  keyHash.update(`${input.managedFile}\0`)
+  for (const file of input.contextFiles) keyHash.update(`${file.path}\0${file.content}\0`)
+  return keyHash.digest('hex')
+}
+
 export default function contextImportsExtension(pi: ExtensionAPI) {
   let localContexts: Array<{ path: string; content: string }> = []
+  // ~/.claude/CLAUDE.md, Claude's user-scope memory (all projects). The user's own
+  // file, so it needs no project approval; read once at session start like the
+  // locals, so a mid-session body edit applies next session, matching Claude.
+  let userContext: { path: string; content: string } | undefined
+  // The project-scope alternate location ./.claude/CLAUDE.md. pi loads ./CLAUDE.md
+  // 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 project settings may contribute claudeMdExcludes; decided at session
   // start with the silent check, so no prompt fires mid-flight.
   let projectApproved = false
@@ -507,6 +623,87 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
     publishInstructionLoad(pi.events, event)
   }
 
+  // before_agent_start fires every turn, but its inputs almost never change
+  // mid-session. The settings-derived environment (managed settings, exclude
+  // globs, repo root) is cached per cwd, and the whole import expansion is
+  // memoized on its inputs and revalidated by a stat token (mtime and size): a
+  // turn where nothing changed costs a handful of stats instead of re-reading and
+  // re-recursing every @import. A brand-new file satisfying a previously missing
+  // @import is picked up when any recorded stat token moves (or next session),
+  // which is already fresher than Claude, which loads context once at session start.
+  let envCache: { cwd: string; managed: Record<string, unknown>; excludeGlobs: string[]; projectRoot: string } | undefined
+  let importMemo:
+    | {
+        key: string
+        extras: Array<{ path: string; content: string; dir: string }>
+        imported: ImportedFile[]
+        budget: ImportBudget
+        tokens: Array<[string, string]>
+      }
+    | undefined
+  // mtime plus size, so a same-mtime rewrite of a different length still invalidates.
+  const statToken = (file: string): string => {
+    const stat = fs.statSync(file)
+    return `${stat.mtimeMs}:${stat.size}`
+  }
+  const memoIsFresh = (memo: NonNullable<typeof importMemo>): boolean => {
+    try {
+      return memo.tokens.every(([file, token]) => statToken(file) === token)
+    } catch {
+      return false // a recorded file vanished: re-expand
+    }
+  }
+  // Memo lookup or recompute: a turn whose key matches the previous expansion and
+  // whose recorded stat tokens are all unchanged reuses that expansion outright;
+  // otherwise the imports are re-expanded and the memo (with a fresh revalidation
+  // 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,
+  ): { extras: Array<{ path: string; content: string; dir: string }>; budget: ImportBudget; imported: ImportedFile[] } => {
+    if (importMemo?.key === memoKey && memoIsFresh(importMemo)) {
+      const { extras, budget, imported } = importMemo
+      return { extras, budget, imported }
+    }
+    // Seed with every loaded context file path, excluded ones included, so pi's own
+    // 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)
+    if (userContext !== undefined) ownPaths.push(userContext.path)
+    if (projectDotClaude !== undefined) ownPaths.push(projectDotClaude.path)
+    ownPaths.push(managedClaudeMdPath())
+    const seenSet = new Set(realRoots(ownPaths))
+
+    // 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)
+
+    // 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)
+
+    // 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).
+    const tokens: Array<[string, string]> = []
+    try {
+      for (const file of [...extras.map((extra) => extra.path), ...imported.map((entry) => entry.path)]) tokens.push([file, statToken(file)])
+      for (const dir of addDirs) tokens.push([dir, statToken(dir)])
+      importMemo = { key: memoKey, extras, budget, imported, tokens }
+    } catch {
+      importMemo = undefined // a file moved mid-expansion: just recompute next turn
+    }
+    return { extras, budget, imported }
+  }
+
   // Claude's --add-dir. Only the memory-loading half is meaningful here: pi has
   // no path-based permission system, so there is no access grant to mirror.
   // Optional-called so the extension still wires under stub hosts without flags.
@@ -520,14 +717,31 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
     // a reload anyway; a reload simply re-fires InstructionsLoaded once per file,
     // which is fine, since a reload re-loads the instruction files.
     announced.clear()
+    envCache = undefined
+    importMemo = undefined
+    localContexts = []
+    userContext = undefined
+    projectDotClaude = undefined
+
+    // ~/.claude/CLAUDE.md, Claude's user-scope memory. The user's own file, so no
+    // project approval is required; a missing file simply leaves it unset.
+    try {
+      const userClaudeMd = path.join(claudeConfigDir(os.homedir()), 'CLAUDE.md')
+      userContext = { path: userClaudeMd, content: fs.readFileSync(userClaudeMd, 'utf-8') }
+    } catch {
+      // no user CLAUDE.md
+    }
+
     // CLAUDE.local.md is Claude Code's personal sidecar of CLAUDE.md; pi's own loader
     // skips it. A cloned repo can ship one, so it is gated like other project config.
     // Claude loads local context from the whole hierarchy above the working
     // directory, ordered root down to cwd; the walk is bounded at the repository
-    // root like every other project-config search here.
-    localContexts = []
+    // root like every other project-config search here. The project-scope alternate
+    // ./.claude/CLAUDE.md (nearest at or above cwd) is repo-controlled too, so both
+    // ride the one approval decision.
     const candidates = ancestorFiles(ctx.cwd, 'CLAUDE.local.md')
-    if (candidates.length > 0 && (await isProjectApproved(ctx))) {
+    const dotClaudeMd = findNearestFile(ctx.cwd, path.join('.claude', 'CLAUDE.md'))
+    if ((candidates.length > 0 || dotClaudeMd !== null) && (await isProjectApproved(ctx))) {
       for (const candidate of candidates) {
         try {
           localContexts.push({ path: candidate, content: fs.readFileSync(candidate, 'utf-8') })
@@ -535,6 +749,13 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
           // unreadable: treat as absent
         }
       }
+      if (dotClaudeMd !== null) {
+        try {
+          projectDotClaude = { path: dotClaudeMd, content: fs.readFileSync(dotClaudeMd, 'utf-8') }
+        } catch {
+          // unreadable: treat as absent
+        }
+      }
     }
     // Read after the local-context flow so an approval it just recorded is honored.
     projectApproved = isProjectApprovedSilently(ctx)
@@ -545,10 +766,12 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
     const cwd = event.systemPromptOptions?.cwd ?? process.cwd()
     const native: Array<{ path: string; content: string }> = event.systemPromptOptions?.contextFiles ?? []
 
-    const managed = readManagedSettings()
-    const excludeGlobs = readClaudeMdExcludes(claudeMdExcludeFiles(cwd, home, projectApproved), managed)
+    if (envCache?.cwd !== cwd) {
+      const managedNow = readManagedSettings()
+      envCache = { cwd, managed: managedNow, excludeGlobs: readClaudeMdExcludes(claudeMdExcludeFiles(cwd, home, projectApproved), managedNow), projectRoot: repoRoot(cwd) ?? cwd }
+    }
+    const { managed, excludeGlobs, projectRoot } = envCache
     const excluded = (absPath: string): boolean => isExcludedPath(absPath, excludeGlobs, home)
-    const projectRoot = repoRoot(cwd) ?? cwd
 
     // claudeMdExcludes drops an excluded file's block from the assembled prompt and
     // from import expansion; surviving blocks get block-level comments stripped.
@@ -563,35 +786,45 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
       announce({ file_path: file.path, memory_type: memoryTypeForPath(file.path, home, projectRoot), load_reason: 'session_start' })
     }
 
-    // Managed claudeMd is honored from managed settings ONLY (the key is ignored in
-    // user and project settings) and is never excludable; it loads before user and
-    // project context, so it goes to the top of the <project_context> block.
-    const managedClaudeMd = typeof managed.claudeMd === 'string' ? stripBlockComments(managed.claudeMd).trim() : ''
-    if (managedClaudeMd.length > 0) {
-      prompt = withManagedBlock(prompt, instructionsBlock(MANAGED_CLAUDE_MD_PATH, managedClaudeMd))
-      changed = true
-    }
-
-    const keptLocals = localContexts.filter((local) => !excluded(local.path)).map((local) => ({ path: local.path, content: stripBlockComments(local.content) }))
-    const contextFiles = [...rewrite.kept, ...keptLocals]
+    // The user CLAUDE.md is the user's own file (no approval gate) but respects
+    // claudeMdExcludes and comment-stripping like every other file. It is kept here so it
+    // both gets its own block (via prependMemoryBlocks) and joins the import-expansion set
+    // below, so its @imports resolve.
+    const keptUser = userContext !== undefined && !excluded(userContext.path) ? { path: userContext.path, content: stripBlockComments(userContext.content) } : undefined
 
-    // Seed with every loaded context file path, excluded ones included, so pi's own
-    // files are never re-imported and an excluded file cannot return as an import.
-    const seenSet = new Set(realRoots([...native, ...localContexts].map((file) => file.path)))
+    // Prepend the managed and user memory blocks (managed file, managed key, user), the
+    // blocks Claude loads ahead of pi's native project context. managedFile comes back
+    // because it also seeds the import memo key below.
+    const top = prependMemoryBlocks(prompt, changed, keptUser, managed, announce)
+    prompt = top.prompt
+    changed = top.changed
+    const managedFile = top.managedFile
 
-    // 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)
-
-    // 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 keptLocals = localContexts.filter((local) => !excluded(local.path)).map((local) => ({ path: local.path, content: stripBlockComments(local.content) }))
 
-    let addition = localContextAddition(keptLocals, announce)
+    // ./.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
+
+    // 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]
+
+    // 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)
+
+    // 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)
+    addition += localContextAddition(keptLocals, announce)
     addition += additionalDirsAddition(extras, announce)
     addition += importedAddition(imported, budget, home, projectRoot, announce)
     if (!changed && addition.length === 0) return

package/extensions/context-usage.ts

@@ -0,0 +1,45 @@
+/**
+ * Context Usage Command
+ *
+ * Claude Code's `/context` reports how much of the model's context window the
+ * current session occupies. This registers a `context` command that reads pi's
+ * live ContextUsage and renders a concise breakdown through notify. pi exposes
+ * three fields (tokens, contextWindow, percent); the used/window/free lines and
+ * the percentage are built from exactly those, with the model's window as a
+ * fallback when the usage snapshot does not carry one.
+ */
+
+import type { ContextUsage, ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+const fmt = (n: number): string => n.toLocaleString('en-US')
+
+/** The breakdown text for a usage snapshot, or a friendly line when there is none.
+ * `tokens` is null right after a compaction (before the next response recounts), so
+ * that case reports a recalculating state instead of a bogus zero. */
+export function formatContextUsage(usage: ContextUsage | undefined, modelWindow?: number): string {
+  if (!usage) {
+    return 'Context usage is not available yet. It appears once the model has responded (and resets right after a compaction).'
+  }
+  const window = usage.contextWindow || modelWindow || 0
+  if (usage.tokens === null) {
+    const tail = window > 0 ? ` Window: ${fmt(window)} tokens.` : ''
+    return `Context usage: recalculating the token count (e.g. right after a compaction).${tail}`
+  }
+  const tokens = usage.tokens
+  const percent = usage.percent ?? (window > 0 ? (tokens / window) * 100 : null)
+  const percentSuffix = percent === null ? '' : ` (${percent.toFixed(1)}%)`
+  const lines = ['Context usage', `  Used:   ${fmt(tokens)} tokens${percentSuffix}`]
+  if (window > 0) {
+    lines.push(`  Window: ${fmt(window)} tokens`, `  Free:   ${fmt(Math.max(window - tokens, 0))} tokens`)
+  }
+  return lines.join('\n')
+}
+
+export default function contextUsageExtension(pi: ExtensionAPI) {
+  pi.registerCommand('context', {
+    description: 'Show how much of the model context window this session is using',
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(formatContextUsage(ctx.getContextUsage(), ctx.model?.contextWindow), 'info')
+    },
+  })
+}

package/extensions/env-settings.ts

@@ -0,0 +1,130 @@
+/**
+ * settings.json `env` injection.
+ *
+ * Claude Code lets any settings scope carry an `env` object whose keys are exported
+ * into the session's environment. This extension applies that chain to process.env:
+ * managed-settings.json (enterprise policy), ~/.claude/settings.json (user), and the
+ * project's .claude/settings.json plus settings.local.json.
+ *
+ * Two things run this. The factory body applies managed + user immediately (as pi
+ * loads extensions), so those variables are present before the first turn; a session
+ * that never approves a project still gets them. session_start refreshes and, only
+ * when the project is approved, folds in the project scope. The project scope stays
+ * approval-gated on purpose: a checked-out repository's env can redirect providers
+ * (ANTHROPIC_BASE_URL and friends), so an untrusted repo must not reach process.env.
+ *
+ * Precedence is per key, managed > user > project, matching Claude's merge: a scope
+ * only supplies keys it names and never wipes another scope's keys. Values must be
+ * strings; a number or boolean is coerced via String, anything else is skipped.
+ *
+ * A variable already present in the real environment that this module did not set is
+ * left untouched for the user and project scopes: a shell `export` outranks them. The
+ * managed scope is the exception: an org policy env must win over an ambient export, so
+ * a managed key overwrites a preexisting shell value. The keys this module sets are
+ * recorded so a later refresh can update them without clobbering unrelated env, and a
+ * key an earlier apply set that the current merge no longer defines is unset (deleted
+ * from process.env), so an approved project's env cannot leak into a later session or
+ * project that does not define it. A managed overwrite of a shell var is owned like any
+ * other set key; its original shell value cannot be restored, so on unset it is deleted.
+ *
+ * Docs: https://code.claude.com/docs/en/settings.md
+ */
+
+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 { findNearestFile } from './internal/project-root.js'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** 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,
+ * array, null) is dropped, matching Claude which only injects string-valued env. */
+export function envFromSettings(settings: unknown): Record<string, string> {
+  const out: Record<string, string> = {}
+  if (!isRecord(settings) || !isRecord(settings.env)) return out
+  for (const [key, value] of Object.entries(settings.env)) {
+    if (typeof value === 'string') out[key] = value
+    else if (typeof value === 'number' || typeof value === 'boolean') out[key] = String(value)
+  }
+  return out
+}
+
+/** Merge the three env scopes with Claude's per-key precedence managed > user >
+ * project: lower scopes are laid down first and higher ones overlay, so each key
+ * takes its highest-precedence value and no scope wipes another's keys. */
+export function mergeEnvScopes(managed: Record<string, string>, user: Record<string, string>, project: Record<string, string>): Record<string, string> {
+  return { ...project, ...user, ...managed }
+}
+
+/** Assign the merged env into `env`, recording each key set into `owned`. A key already
+ * present that this module did not set (a shell export) is left untouched for user and
+ * project keys; a `managedKeys` entry overwrites it (an org policy outranks the shell).
+ * A key this module set before is updated. A previously-owned key that the current
+ * `merged` no longer defines is unset (deleted from `env` and `owned`), so an approved
+ * project's env cannot leak into a later apply that does not define it. */
+export function applyEnvSettings(merged: Record<string, string>, env: NodeJS.ProcessEnv, owned: Set<string>, managedKeys: ReadonlySet<string> = new Set()): void {
+  // Unset any key an earlier apply set that the current merge dropped. Iterate a copy
+  // since `owned` is mutated. A shell export this module never owned is left in place.
+  for (const key of Array.from(owned)) {
+    if (!(key in merged)) {
+      delete env[key]
+      owned.delete(key)
+    }
+  }
+  for (const [key, value] of Object.entries(merged)) {
+    // A shell export outranks user/project (skip), but a managed key outranks even the
+    // shell. Once owned, updates always apply. A managed overwrite is owned like any
+    // set key: its shell value is gone and cannot be restored, so on unset it is deleted.
+    if (key in env && !owned.has(key) && !managedKeys.has(key)) continue
+    env[key] = value
+    owned.add(key)
+  }
+}
+
+function readSettingsFile(file: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'))
+    if (isRecord(parsed)) return parsed
+  } catch {
+    // missing or invalid file: no env from this scope
+  }
+  return {}
+}
+
+/** The user scope's env: ~/.claude/settings.json (relocated by CLAUDE_CONFIG_DIR). */
+function userEnv(home: string): Record<string, string> {
+  return envFromSettings(readSettingsFile(path.join(claudeConfigDir(home), 'settings.json')))
+}
+
+/** The project scope's env: .claude/settings.json with settings.local.json overlaid,
+ * each the nearest of its name at or above cwd (matching the hooks settings chain). */
+function projectEnv(cwd: string): Record<string, string> {
+  const base = envFromSettings(readSettingsFile(findNearestFile(cwd, path.join('.claude', 'settings.json')) ?? path.join(cwd, '.claude', 'settings.json')))
+  const local = envFromSettings(readSettingsFile(findNearestFile(cwd, path.join('.claude', 'settings.local.json')) ?? path.join(cwd, '.claude', 'settings.local.json')))
+  return { ...base, ...local }
+}
+
+export default function envSettingsExtension(pi: ExtensionAPI) {
+  const owned = new Set<string>()
+
+  const apply = (home: string, project: Record<string, string>): void => {
+    const managed = envFromSettings(readManagedSettings())
+    applyEnvSettings(mergeEnvScopes(managed, userEnv(home), project), process.env, owned, new Set(Object.keys(managed)))
+  }
+
+  // Factory time: managed + user only. Approval needs the session ctx, so the project
+  // scope waits for session_start; running here means these vars land before the first turn.
+  apply(os.homedir(), {})
+
+  pi.on('session_start', async (_event, ctx: ExtensionContext) => {
+    apply(os.homedir(), isProjectApprovedSilently(ctx) ? projectEnv(ctx.cwd) : {})
+  })
+}