pi-code 1.0.63 → 1.0.65

package/extensions/hooks/runners.ts

@@ -6,11 +6,11 @@
 
 import { type ChildProcess, spawn } from 'node:child_process'
 import * as fs from 'node:fs'
-import * as path from 'node:path'
 import type { Api, Model } from '@earendil-works/pi-ai'
 import { runAgent } from '../internal/agent-run.js'
 import { callMcpTool } from '../internal/mcp-call.js'
 import { completeText } from '../internal/model-complete.js'
+import { killProcessTree } from '../internal/process-tree.js'
 import { resolveShell } from '../internal/shell-resolve.js'
 import { errorMessage } from '../internal/values.js'
 import { type HookCommand, httpUrlAllowed, isBackgroundHook } from './config.js'
@@ -41,10 +41,6 @@ export interface HookRunResult {
 }
 /** Runs one configured hook entry, whatever its type; boundRunner dispatches. */
 export type HookRunner = (hook: HookCommand, payload: unknown, timeoutMs: number) => Promise<HookRunResult>
-/** The shell path specifically; the statusline reuses it for its own command. With an
- * `args` array it becomes the exec path: `command` is spawned directly with those args.
- * `onChild` hands the caller a kill for the spawned tree, so a background hook that is
- * still running at session end can be reaped (Claude kills async hooks at teardown). */
 /** How one command hook is spawned, beyond the payload and its budget. Grouped rather
  * than trailing off the parameter list: the exec form, the shell choice and the
  * declaring plugin are all per-hook fields that arrive together from one HookCommand. */
@@ -96,30 +92,9 @@ const MAX_HOOK_OUTPUT = 1_000_000
 /** Conventional exit code for a killed-on-timeout command, as `timeout(1)` reports it. */
 const TIMEOUT_EXIT_CODE = 124
 
-/**
- * Kill the shell and everything it spawned. `sh -c 'a; b'` forks, so signalling the
- * direct child alone leaves a grandchild alive holding stdout/stderr.
- */
+/** Kill the shell and everything it spawned; see internal/process-tree. */
 function killTree(child: ChildProcess): void {
-  if (process.platform === 'win32') {
-    // Windows has no process groups: taskkill /T ends the shell's whole tree. By
-    // absolute path, so a writable PATH entry cannot stand in for it. If taskkill itself
-    // cannot start, the direct kill is all that is left.
-    const taskkill = path.join(process.env.SystemRoot ?? String.raw`C:\Windows`, 'System32', 'taskkill.exe')
-    if (child.pid) spawn(taskkill, ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }).on('error', () => child.kill('SIGKILL'))
-    else child.kill('SIGKILL')
-    return
-  }
-  try {
-    // Negative pid targets the whole process group, which `detached` gave the shell.
-    if (child.pid) {
-      process.kill(-child.pid, 'SIGKILL')
-      return
-    }
-  } catch {
-    // Group already reaped, or the platform refused it; fall through to the direct kill.
-  }
-  child.kill('SIGKILL')
+  killProcessTree(child, 'SIGKILL')
 }
 
 /** Create the plugin data directory the moment its path is handed to a child. Claude
@@ -140,6 +115,10 @@ function shellInvocation(command: string, shell: string | undefined): { file: st
   return resolved ? { file: resolved.file, spawnArgs: resolved.argsFor(command) } : undefined
 }
 
+/** The shell path specifically; the statusline reuses it for its own command. With an
+ * `args` array it becomes the exec path: `command` is spawned directly with those args.
+ * `onChild` hands the caller a kill for the spawned tree, so a background hook that is
+ * still running at session end can be reaped (Claude kills async hooks at teardown). */
 export const runHookCommand: HookCommandRunner = (command, payload, timeoutMs, { projectDir, args, onChild, shell, plugin, sessionId } = {}) =>
   new Promise((resolve) => {
     // /bin/sh by absolute path off Windows, so the shell can't be resolved through an

package/extensions/internal/agent-run.ts

@@ -36,7 +36,7 @@ export function setAgentRunner(fn: AgentRunner | undefined): void {
   runner = fn
 }
 
-/** Whether a runner is registered, so agent hooks can be reported as runnable. */
+/** Test seam: whether a runner is registered. */
 export function hasAgentRunner(): boolean {
   return runner !== undefined
 }

package/extensions/internal/bash-rules.ts

@@ -11,8 +11,7 @@
  */
 
 import { hasSubstitution, splitSegments } from './shell-split.js'
-
-const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
+import { escapeRegExp } from './values.js'
 
 /**
  * One rule against one command segment, per Claude's permission table:

package/extensions/internal/claude-tool-names.ts

@@ -1,13 +1,10 @@
 /**
  * The one place pi tool names and Claude tool names are paired.
  *
- * Two independent tables used to encode this: a Claude->pi map for resolving
- * `allowed-tools` entries, and a pi->Claude map for hook payloads and matchers.
- * They disagreed. The second one listed six tools, so a hook matcher written in
- * Claude's vocabulary never fired for `web_fetch`, `subagent`, `question`, `todo`,
- * `slash_command`, `web_search` or `plan_mode_complete`, even though the first table
- * had known those pairings all along. Both directions now derive from this list, so
- * a tool cannot be nameable in one direction and invisible in the other.
+ * Both directions (the Claude->pi map that resolves `allowed-tools` entries, and the
+ * pi->Claude map behind hook payloads and matchers) derive from this one list, so a
+ * tool cannot be nameable in one direction and invisible in the other: two separate
+ * tables let a hook matcher written in Claude's vocabulary miss seven tools.
  *
  * Canonical names are the tools reference's own spellings. `claude: null` marks a pi
  * tool the reference has no counterpart for: it stays untranslated in payloads, and

package/extensions/internal/command-file.ts

@@ -19,6 +19,7 @@ import * as path from 'node:path'
 import { parseFrontmatter } from '@earendil-works/pi-coding-agent'
 
 import { CLAUDE_TOOL_MAP } from './claude-tool-names.js'
+import { escapeRegExp } from './values.js'
 
 /** The pi file tools a Claude path rule can govern. */
 export type PathRuleTool = 'read' | 'edit' | 'write'
@@ -256,7 +257,7 @@ const text = (value: unknown): string => {
  * number rather than a boolean. A flag that gates a command off from the model has to
  * honor them, or a command the user marked off-limits is silently offered to it. */
 const YAML_TRUE = new Set(['true', 'yes', 'on', 'y', '1'])
-const isFlagEnabled = (value: unknown): boolean => value === true || YAML_TRUE.has(text(value).toLowerCase())
+export const isFlagEnabled = (value: unknown): boolean => value === true || YAML_TRUE.has(text(value).toLowerCase())
 
 /** YAML's negative boolean spellings, the mirror of YAML_TRUE. A flag that defaults to
  * true (user-invocable) is turned off only by one of these; any other value, absent
@@ -332,8 +333,6 @@ function splitArgs(args: string): string[] {
   return out
 }
 
-const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
-
 /** One alternation covering every argument placeholder plus the two escape forms.
  * Alternation order is load-bearing: escapes first (so `\$1` never expands), the
  * bracketed forms before `$ARGUMENTS` (so `$ARGUMENTS[0]` is not read as the bare

package/extensions/internal/external-imports.ts

@@ -11,10 +11,9 @@
  * 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.
+ * able to move its own key: `.git` cannot be committed, so nothing a repository ships
+ * changes where its own decisions are stored. A separate worktree of one repository
+ * is a separate checkout and is asked separately.
  */
 
 import * as fs from 'node:fs'
@@ -37,7 +36,7 @@ export function externalImportKey(cwd: string): string {
   }
 }
 
-/** The store file. A seam: the tests point it at a temp directory. */
+/** The store file, inside pi's agent directory (tests relocate that through PI_CODING_AGENT_DIR). */
 export function externalImportStorePath(agentDir: string = getAgentDir()): string {
   return path.join(agentDir, 'pi-code-external-imports.json')
 }

package/extensions/internal/goal-evaluator.ts

@@ -6,6 +6,8 @@
  * so goal.ts stays the lifecycle wiring and each contract is pinned on its own.
  */
 
+import { parseNumericEnv } from './values.js'
+
 /** Claude caps a goal condition at 4,000 characters. */
 export const GOAL_CONDITION_MAX_CHARS = 4000
 
@@ -238,9 +240,8 @@ export const MAX_IDLE_CHECKINS = 3
  * goal: CLAUDE_CODE_GOAL_CHECKIN_MINUTES (0 turns check-ins off, junk falls back to
  * the default) scaled by Claude's doubling. */
 export function checkinIntervalMs(env: Record<string, string | undefined>, delivered: number): number {
-  const raw = env.CLAUDE_CODE_GOAL_CHECKIN_MINUTES
-  const parsed = raw === undefined || raw.trim() === '' ? Number.NaN : Number(raw)
-  const minutes = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_CHECKIN_MINUTES
+  const parsed = parseNumericEnv(env.CLAUDE_CODE_GOAL_CHECKIN_MINUTES)
+  const minutes = parsed !== undefined && parsed >= 0 ? parsed : DEFAULT_CHECKIN_MINUTES
   return minutes * 60_000 * 2 ** Math.min(delivered, MAX_CHECKIN_DOUBLINGS)
 }
 

package/extensions/internal/instruction-events.ts

@@ -49,11 +49,11 @@ export function memoryTypeForPath(filePath: string, home: string, projectRoot: s
   if (path.basename(filePath) === 'CLAUDE.local.md') return 'Local'
   const isUnder = (root: string): boolean => root.length > 0 && (filePath === root || filePath.startsWith(root + path.sep))
   if (isUnder(projectRoot)) return 'Project'
-  // Monorepo: repoRoot stops at the nearest .git OR package.json, so a git-root
-  // CLAUDE.md can sit above the projectRoot a subpackage session reports. A file
-  // whose directory is a strict ancestor of the project root is still project
-  // memory. The home directory itself stays User: a home-level context file is
-  // user config even when the project lives under home.
+  // Nested repositories: repoRoot stops at the nearest .git, so a session inside a
+  // nested checkout reports it as the project root while the outer repository's
+  // CLAUDE.md sits above it. A file whose directory is a strict ancestor of the
+  // project root is still project memory. The home directory itself stays User: a
+  // home-level context file is user config even when the project lives under home.
   const dir = path.dirname(filePath)
   if (dir !== home && (projectRoot === dir || projectRoot.startsWith(dir + path.sep))) return 'Project'
   if (isUnder(home)) return 'User'

package/extensions/internal/managed-settings.ts

@@ -17,7 +17,7 @@ import { isRecord } from './values.js'
 /** The OS managed-settings.json path Claude Code documents per platform. */
 export function managedSettingsPath(platform: NodeJS.Platform = process.platform): string {
   if (platform === 'darwin') return '/Library/Application Support/ClaudeCode/managed-settings.json'
-  // The legacy C:\ProgramData\ClaudeCode path was dropped in Claude Code v2.1.75.
+  // Claude reads the Windows file from Program Files; the older ProgramData location is not consulted.
   if (platform === 'win32') return String.raw`C:\Program Files\ClaudeCode\managed-settings.json`
   return '/etc/claude-code/managed-settings.json'
 }

package/extensions/internal/mcp-oauth.ts

@@ -61,8 +61,8 @@ function storeFileFor(serverName: string, endpoint?: string): string {
     .digest('hex')
     .slice(0, 8)
   // Collapse disallowed runs to a single hyphen, then strip leading and trailing
-  // hyphens by index. The old /^-+|-+$/g trim rescanned on every hyphen of a long run
-  // (its trailing-anchored branch backtracks per start position), which is quadratic.
+  // hyphens by index: a trailing-anchored regex trim rescans per hyphen of a long run
+  // (quadratic).
   const collapsed = serverName.replace(/[^A-Za-z0-9_-]+/g, '-')
   let start = 0
   let end = collapsed.length
@@ -248,7 +248,17 @@ export function waitForAuthCode(server: http.Server, timeoutMs: number, expected
     // abandoned or resolved out of band, the event loop can still drain.
     timer.unref?.()
     server.on('request', (request, response) => {
-      const url = new URL(request.url ?? '/', 'http://127.0.0.1')
+      // Node's parser passes an absolute-form target through unvalidated, and a throw
+      // from a 'request' listener is not caught by node:http: it was an
+      // uncaughtException during the login window, from any local process that could
+      // reach the port.
+      let url: URL
+      try {
+        url = new URL(request.url ?? '/', 'http://127.0.0.1')
+      } catch {
+        response.writeHead(400).end()
+        return
+      }
       // Only the redirect path settles the login. A stray request (a favicon fetch, a
       // local port scan, or a forged redirect from another process or an open web page)
       // is answered but ignored, so it can neither inject a code nor abort the login by

package/extensions/internal/model-complete.ts

@@ -59,7 +59,13 @@ export interface CompleteOptions {
  * tool call, only assistant text.
  */
 export async function completeText(model: Model<Api>, prompt: string, options: CompleteOptions = {}): Promise<{ text: string; usage: Usage }> {
-  backend ??= realBackend()
+  // A rejected creation must not stay cached: ModelRuntime.create can fail on a
+  // transient (a credential store read), and caching that promise made every later
+  // call rethrow the same stale error for the life of the process.
+  backend ??= realBackend().catch((error: unknown) => {
+    backend = null
+    throw error
+  })
   const complete = await backend
   const context: Context = {
     systemPrompt: options.system,

package/extensions/internal/model-lookup.ts

@@ -11,10 +11,17 @@ export interface ModelLookupContext<M> {
   modelRegistry?: { getAvailable?: () => ReadonlyArray<{ id: string; name?: string }> }
 }
 
+/** The one fuzzy model rule every surface shares (goal, prompt hooks, commands,
+ * subagent aliases): an exact id (case-insensitive) first, then a substring of the
+ * id or the display name. Three private copies had diverged, so `model: opus` could
+ * resolve differently per surface. */
+export function findModel<M extends { id: string; name?: string }>(needle: string, available: ReadonlyArray<M>): M | undefined {
+  const wanted = needle.toLowerCase()
+  return available.find((model) => model.id.toLowerCase() === wanted) ?? available.find((model) => model.id.toLowerCase().includes(wanted) || model.name?.toLowerCase().includes(wanted))
+}
+
 export function resolveModelOverride<M>(ctx: ModelLookupContext<M>, override: string | undefined): M | undefined {
   if (!override) return ctx.model
   const available = ctx.modelRegistry?.getAvailable?.() ?? []
-  const needle = override.toLowerCase()
-  const match = available.find((model) => model.id.toLowerCase() === needle) ?? available.find((model) => model.id.toLowerCase().includes(needle) || model.name?.toLowerCase().includes(needle))
-  return (match as M | undefined) ?? ctx.model
+  return (findModel(override, available) as M | undefined) ?? ctx.model
 }

package/extensions/internal/path-rules.ts

@@ -14,6 +14,7 @@
  */
 
 import * as path from 'node:path'
+import { escapeRegExp } from './values.js'
 
 export interface PathAnchors {
   cwd: string
@@ -21,8 +22,6 @@ export interface PathAnchors {
   home: string
 }
 
-const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
-
 /** Cap on brace-expanded alternatives per pattern, mirroring Claude's ~1000
  * budget; an over-budget pattern is used unexpanded. */
 const BRACE_EXPANSION_LIMIT = 1000
@@ -104,9 +103,9 @@ function bracketClass(body: string): string | null {
   // JavaScript will build: RegExp throws "Range out of order in character class". The
   // `-` cannot simply be escaped, since `[a-z]` is the whole point of the syntax, so the
   // class is validated by construction and an unbuildable one is treated exactly as an
-  // unterminated `[` already is: the pattern is invalid and matches nothing. Without
-  // this the throw escaped compileGlobs, which does not catch, and took the permission
-  // check that called it with it.
+  // unterminated `[` already is: the pattern is invalid and matches nothing. It must
+  // not throw: compileGlobs does not catch, and the permission check that called it
+  // would fail with it.
   return isBuildableClass(source) ? source : null
 }
 
@@ -196,9 +195,7 @@ function resolveRule(rule: string, anchors: PathAnchors): string {
   return path.join(anchors.cwd, rel)
 }
 
-/** One rule glob precompiled for repeated matching: its anchored regex, and whether
- * it applies to the basename (a slashless pattern, gitignore-style) or the full
- * root-relative path. */
+/** One rule glob precompiled for repeated matching: its anchored regex. */
 export interface CompiledGlob {
   regex: RegExp
 }
@@ -212,13 +209,13 @@ export function globCompileStats(): { compiled: number; evaluated: number } {
   return { compiled: globsCompiled, evaluated: globsEvaluated }
 }
 
-/** Rule `paths:` globs compiled once for repeated matching, with claude-rules'
- * pathMatchesGlobs semantics: `./` and leading `/` anchors are stripped, a trailing
- * slash scopes to the directory's contents, and blank entries drop out. */
 /** Claude's shared list budget: rule patterns past ~1000 compiled entries are
  * ignored rather than compiled without bound. */
 const LIST_PATTERN_BUDGET = 1000
 
+/** Rule `paths:` globs compiled once for repeated matching, with claude-rules'
+ * pathMatchesGlobs semantics: `./` and leading `/` anchors are stripped, a trailing
+ * slash scopes to the directory's contents, and blank entries drop out. */
 export function compileGlobs(globs: string[]): CompiledGlob[] {
   const compiled: CompiledGlob[] = []
   for (const raw of globs) {
@@ -244,8 +241,6 @@ export function matchesCompiledGlobs(relPath: string, globs: CompiledGlob[]): bo
   return globs.some((glob) => glob.regex.test(posix))
 }
 
-/** Whether the accessed file matches at least one rule. No rules means no match:
- * a granted-but-scoped tool with an empty scope set stays blocked, never open. */
 /** Both comparison sides in posix form. On Windows, resolve stamps the drive on
  * the target while join-built rules stay drive-less, and backslash separators
  * collide with glob syntax, so unnormalized rules could never match. */
@@ -273,6 +268,8 @@ export function stripRuleDrive(rule: string, windows: boolean): string {
   return rule.replace(/^([A-Za-z]):\//, '/').replace(/^\/[A-Za-z]\//, '/')
 }
 
+/** Whether the accessed file matches at least one rule. No rules means no match:
+ * a granted-but-scoped tool with an empty scope set stays blocked, never open. */
 export function matchesPathRules(filePath: string, rules: string[], anchors: PathAnchors): boolean {
   const target = toPosix(path.resolve(anchors.cwd, filePath))
   return rules.some((rule) => {

package/extensions/internal/plugins.ts

@@ -258,11 +258,6 @@ function resolvePlugin(home: string, cacheDir: string, marketplace: string, plug
   return { name, root, dataDir: path.join(claudeConfigDir(home), 'plugins', 'data', id), manifest, ...(userConfig ? { userConfig } : {}) }
 }
 
-/** The two plugin path variables, textually substituted into plugin-shipped
- * config (hook commands, MCP server definitions, command bodies). A caller
- * substituting into text that is still raw JSON must pass an escapeValue that
- * JSON-escapes: a Windows root (C:\Users\...) inserted verbatim injects invalid
- * escape sequences and the subsequent parse throws. */
 /** A plugin component path, resolved inside the plugin root. Claude "rejects a component
  * path that resolves outside the plugin root, such as `../shared-utils`", so an escaping
  * entry yields undefined and its caller skips that component. The check is lexical, which
@@ -277,6 +272,11 @@ export function pluginComponentPath(plugin: Pick<InstalledPlugin, 'name' | 'root
   return resolved
 }
 
+/** The two plugin path variables, textually substituted into plugin-shipped
+ * config (hook commands, MCP server definitions, command bodies). A caller
+ * substituting into text that is still raw JSON must pass an escapeValue that
+ * JSON-escapes: a Windows root (C:\Users\...) inserted verbatim injects invalid
+ * escape sequences and the subsequent parse throws. */
 export function substitutePluginVars(value: string, plugin: InstalledPlugin, escapeValue: (substituted: string) => string = (substituted) => substituted): string {
   return value
     .replaceAll('${CLAUDE_PLUGIN_ROOT}', escapeValue(plugin.root))

package/extensions/internal/process-tree.ts

@@ -0,0 +1,39 @@
+/**
+ * Kill a detached child and everything it spawned. `sh -c 'a; b'` forks, and so does
+ * a child pi running a build, so signalling the direct child alone leaves a grandchild
+ * alive holding stdout/stderr. One copy for hooks and both subagent runners: the three
+ * private copies had drifted, and only the hooks one handled Windows, so a subagent
+ * cancel there killed the direct child only.
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process'
+import * as path from 'node:path'
+
+export function killProcessTree(child: ChildProcess, signal: NodeJS.Signals, platform: NodeJS.Platform = process.platform): void {
+  if (platform === 'win32') {
+    // Windows has no process groups: taskkill /T ends the whole tree, and it has no
+    // graceful signal, so SIGTERM and SIGKILL both force. By absolute path, so a
+    // writable PATH entry cannot stand in for it. If taskkill itself cannot start, or
+    // there is no pid to hand it, the direct kill with the requested signal is all
+    // that is left (Node maps either signal to TerminateProcess there).
+    const taskkill = path.join(process.env.SystemRoot ?? String.raw`C:\Windows`, 'System32', 'taskkill.exe')
+    if (child.pid) spawn(taskkill, ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }).on('error', () => child.kill(signal))
+    else child.kill(signal)
+    return
+  }
+  try {
+    // Negative pid targets the whole process group, which `detached` gave the child.
+    // A child that never spawned has no pid and no group; the direct kill is all there is.
+    if (child.pid) {
+      process.kill(-child.pid, signal)
+      return
+    }
+  } catch {
+    // Group already reaped, or the platform refused it; fall through to the direct kill.
+  }
+  try {
+    child.kill(signal)
+  } catch {
+    // already gone
+  }
+}

package/extensions/internal/project-approval.ts

@@ -118,13 +118,6 @@ function runtimeLacksProjectTrust(ctx: { isProjectTrusted?: () => boolean; ui?:
   return true
 }
 
-/**
- * Whether project-controlled config may be acted on.
- *
- * Refuses without a UI rather than deferring: pi reached this point without consulting
- * `defaultProjectTrust` at all, so there is no user preference to fall back on. A run
- * that cannot ask has not been approved.
- */
 /** The same decision as isProjectApproved, but never prompts: an undecided project
  * reads as unapproved. For surfaces that only display project config, like the
  * subagent roster, where a mid-turn dialog would be wrong. */
@@ -150,6 +143,13 @@ export function isGatedFileApproved(ctx: Pick<ApprovalContext, 'cwd' | 'isProjec
   return isProjectApprovedSilently(ctx, { ...deps, hasClaudeShaped: () => true })
 }
 
+/**
+ * Whether project-controlled config may be acted on.
+ *
+ * Refuses without a UI rather than deferring: pi reached this point without consulting
+ * `defaultProjectTrust` at all, so there is no user preference to fall back on. A run
+ * that cannot ask has not been approved.
+ */
 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

@@ -16,11 +16,10 @@ import * as path from 'node:path'
 /** The project root marker. `.git` is a file in worktrees and submodules, a directory
  * in an ordinary clone.
  *
- * `package.json` used to count too, which made every package of a monorepo its own
- * project: its own memory directory, its own settings.local.json, its own
- * CLAUDE_PROJECT_DIR, its own trust decision. Claude's project is the repository, and
- * a repository can add a package.json wherever it likes, so a marker it controls was
- * also a marker it could move. */
+ * Only `.git`: a package.json marker would make every package of a monorepo its own
+ * project (its own memory directory, settings.local.json, CLAUDE_PROJECT_DIR and trust
+ * decision), and a repository can add a package.json wherever it likes, so a marker it
+ * controls is a marker it can move. Claude's project is the repository. */
 export const ROOT_MARKERS = ['.git']
 
 /** Project root at or above `from`, or undefined outside a repository. */
@@ -32,11 +31,12 @@ 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.
+ * Narrower than repoRoot on purpose: repoRoot resolves a worktree to its main checkout,
+ * which is the right key for shared state (settings.local.json, auto memory) but is a
+ * sibling of the worktree, never an ancestor. The upward walks above bound themselves
+ * here instead, since a boundary that is not on the path from cwd to / is never reached
+ * and the walk would run on to the filesystem root. `.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
@@ -89,7 +89,7 @@ function statOf(target: string): fs.Stats | null {
 }
 
 function findNearest(cwd: string, relative: string, wantDir: boolean): string | null {
-  const boundary = repoRoot(cwd) ?? cwd
+  const boundary = gitRoot(cwd) ?? cwd
   let currentDir = cwd
   while (true) {
     const candidate = path.join(currentDir, relative)
@@ -117,7 +117,7 @@ export function findNearestFile(cwd: string, relative: string): string | null {
  * matching Claude's "every .claude/<kind> between the working directory and the
  * repository root" discovery where the entry closest to cwd wins a name clash. */
 export function ancestorDirs(cwd: string, relative: string): string[] {
-  const boundary = repoRoot(cwd) ?? cwd
+  const boundary = gitRoot(cwd) ?? cwd
   const found: string[] = []
   let currentDir = cwd
   while (true) {
@@ -134,7 +134,7 @@ export function ancestorDirs(cwd: string, relative: string): string[] {
 /** Every `relative` file between the repository root and cwd, ordered root first,
  * matching Claude's root-down ordering for hierarchy-loaded context. */
 export function ancestorFiles(cwd: string, relative: string): string[] {
-  const boundary = repoRoot(cwd) ?? cwd
+  const boundary = gitRoot(cwd) ?? cwd
   const found: string[] = []
   let currentDir = cwd
   while (true) {

package/extensions/internal/settings-chain.ts

@@ -52,12 +52,31 @@ export function claudeSettingsChain(cwd: string, home: string, includeProject: b
   const files = [path.join(claudeConfigDir(home), 'settings.json')]
   if (!includeProject) return files
   files.push(path.join(cwd, '.claude', 'settings.json'))
+  // Compared as the directory the placement rule returned, not re-derived from a
+  // joined path: path.join normalizes separators, so a cwd given POSIX-style on
+  // Windows would never equal its own joined form and the legacy entry would repeat.
   const localDir = localSettingsDir(cwd, home, platform, owned)
   if (localDir !== cwd) files.push(path.join(cwd, '.claude', 'settings.local.json'))
   files.push(path.join(localDir, '.claude', 'settings.local.json'))
   return files
 }
 
+/** The settings.local.json the chain reads last, which is also where a setting a
+ * command persists (an output-style choice, an MCP consent) must be written for the
+ * chain to read it back: a file at any other level is never consulted. */
+export function localSettingsFile(cwd: string, home: string, platform: NodeJS.Platform = process.platform, owned: (paths: string[]) => boolean = ownedByUser): string {
+  return path.join(localSettingsDir(cwd, home, platform, owned), '.claude', 'settings.local.json')
+}
+
+/** One settings file as a JSON object, or undefined when missing, unparseable or not
+ * an object: the single-file case of the chain, for the user-only settings a
+ * repository must not influence (a notification channel, a question timeout, a
+ * retention period). */
+export function readSettingsFile(file: string): Record<string, unknown> | undefined {
+  const first = readSettingsChain([file]).next()
+  return first.done ? undefined : first.value
+}
+
 /** Every readable settings object in the chain, in order, so the last one a caller
  * sees for a key is the one that wins. A file that is missing, unparseable, or not a
  * JSON object is skipped: a corrupt settings.json must not end the chain, or the

package/extensions/internal/settings-watch.ts

@@ -6,6 +6,7 @@
  */
 
 import * as fs from 'node:fs'
+import { parseNumericEnv } from './values.js'
 
 // Captured at module load: the poll must run on real time even under a test's
 // fake timers (the stat watcher it replaced lived in libuv and was immune too);
@@ -29,7 +30,8 @@ function snapshot(file: string): string | undefined {
  * small, so re-reading them on the poll is negligible. The interval is
  * env-tunable for tests. */
 export function watchSettingsFiles(files: string[], reload: () => void): () => void {
-  const interval = Number(process.env.PI_CODE_SETTINGS_WATCH_INTERVAL_MS) || 2000
+  const configured = parseNumericEnv(process.env.PI_CODE_SETTINGS_WATCH_INTERVAL_MS)
+  const interval = configured !== undefined && configured > 0 ? configured : 2000
   let last = files.map(snapshot)
   const timer = realSetInterval(() => {
     const next = files.map(snapshot)

package/extensions/internal/shell-resolve.ts

@@ -70,7 +70,9 @@ export function resolvePowershellBinary(platform: string = process.platform, env
 function isProjectTooling(dir: string, cwd: string): boolean {
   const relative = path.relative(cwd, dir)
   if (relative === '') return true
-  if (relative.startsWith('..') || path.isAbsolute(relative)) return false
+  // Lexical containment: `..tools/...` is a directory inside cwd, only `..` itself or
+  // `../...` leaves it (the shape claude-rules.ts's containment check spells out).
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return false
   return relative.split(path.sep).some((segment) => PROJECT_TOOLING_DIRS.has(segment))
 }
 

package/extensions/internal/tool-target.ts

@@ -1,11 +1,10 @@
 /**
  * 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.
+ * pi's read, edit and write tools accept `file_path` as an alias for `path`, so every
+ * reader of a file tool's target must accept both, and a handler reading only `path`
+ * does nothing for a model that used the alias. This is the one reader (claude-rules,
+ * context-imports and the command path-scope guard all go through it).
  */
 
 /** The tools that name a file pi-code acts on. */

package/extensions/internal/values.ts

@@ -1,8 +1,7 @@
 /**
- * The shapes every extension here needed its own copy of: an error's message, a plain
- * object check, whether a path is a directory, and the text of a message content. Each
- * was written three to five times with the same body, and the error one appeared in
- * seventeen files.
+ * The small shared shapes: an error's message, a plain-object check, whether a path
+ * is a directory, the text of a message content, a regex escape, a numeric env
+ * value. One copy each; a private copy in an extension is the drift to look for.
  */
 
 import * as fs from 'node:fs'
@@ -36,3 +35,20 @@ export function contentText(content: unknown, separator = ''): string {
     .map((part) => part.text)
     .join(separator)
 }
+
+/** Escape a string for literal use inside a RegExp. One copy: five private ones had
+ * the same body and would have drifted the first time one of them was fixed. */
+export function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
+}
+
+/** A numeric environment value, or undefined when blank or not a number. Accepts the
+ * spellings docs/mcp.md promises (`2e3`, `64_000`); the caller decides the range and
+ * whether fractions are meaningful, so no flooring here. */
+export function parseNumericEnv(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined
+  const cleaned = raw.replaceAll('_', '')
+  if (cleaned.trim() === '') return undefined
+  const value = Number(cleaned)
+  return Number.isFinite(value) ? value : undefined
+}