pi-code 1.0.3 → 1.0.5

package/extensions/internal/managed-settings.ts

@@ -0,0 +1,38 @@
+/**
+ * Managed settings: Claude's enterprise policy file.
+ *
+ * Claude Code reads managed-settings.json from an OS-level location that IT
+ * deploys and that is not user- or repo-writable in the normal flow, so keys
+ * sourced from it carry organizational authority (managed `claudeMd`, exclusion
+ * lists, MCP allow/deny). Managed-only keys are honored from this file alone:
+ * the same key in user or project settings is ignored, so a repository or a
+ * local settings edit can neither impersonate nor override the policy.
+ */
+
+import * as fs from 'node:fs'
+
+/** 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.
+  if (platform === 'win32') return 'C:\\Program Files\\ClaudeCode\\managed-settings.json'
+  return '/etc/claude-code/managed-settings.json'
+}
+
+let managedSettingsFileOverride: string | undefined
+
+/** Test seam: override the managed-settings.json path readers consult. */
+export function setManagedSettingsPath(file?: string): void {
+  managedSettingsFileOverride = file
+}
+
+/** The parsed managed settings object, or {} when absent or malformed. */
+export function readManagedSettings(file: string = managedSettingsFileOverride ?? managedSettingsPath()): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed as Record<string, unknown>
+  } catch {
+    // No managed policy on this machine.
+  }
+  return {}
+}

package/extensions/internal/mcp-call.ts

@@ -0,0 +1,28 @@
+/**
+ * A one-function seam letting the hooks extension invoke a tool on a server the
+ * mcp extension has connected, without the two extensions importing each other.
+ *
+ * The mcp extension registers a caller once its clients exist; anything that needs
+ * to call an MCP tool (today: Claude's `type: "mcp_tool"` hooks) goes through
+ * callMcpTool. It is the direct-call analogue of the MCP_TOOLS_CHANNEL alias bus.
+ */
+
+export interface McpToolResult {
+  text: string
+  isError: boolean
+}
+
+export type McpToolCaller = (server: string, tool: string, input: Record<string, unknown>) => Promise<McpToolResult>
+
+let caller: McpToolCaller | undefined
+
+/** The mcp extension registers its caller here; pass undefined to clear it. */
+export function setMcpToolCaller(fn: McpToolCaller | undefined): void {
+  caller = fn
+}
+
+/** Invoke a tool on a connected MCP server. Throws when no server is connected. */
+export function callMcpTool(server: string, tool: string, input: Record<string, unknown>): Promise<McpToolResult> {
+  if (!caller) return Promise.reject(new Error(`no MCP server connected to serve ${server}/${tool}`))
+  return caller(server, tool, input)
+}

package/extensions/internal/mcp-oauth.ts

@@ -0,0 +1,171 @@
+/**
+ * OAuth for remote MCP servers, through the MCP SDK's authProvider seam.
+ *
+ * Claude Code authenticates remote HTTP servers via OAuth from its /mcp panel;
+ * here the flow runs at connect time: a 401 surfaces as UnauthorizedError, the
+ * user approves opening the browser, a one-shot localhost listener catches the
+ * redirect, and the SDK's finishAuth exchanges the code. Tokens, the dynamic
+ * client registration and the PKCE verifier persist per server under pi's agent
+ * directory with owner-only permissions, so later sessions reconnect silently
+ * and refresh through the SDK without a browser round-trip.
+ */
+
+import { spawn } from 'node:child_process'
+import * as crypto from 'node:crypto'
+import * as fs from 'node:fs'
+import * as http from 'node:http'
+import * as path from 'node:path'
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js'
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js'
+
+interface StoredAuth {
+  client?: OAuthClientInformationMixed
+  tokens?: OAuthTokens
+  verifier?: string
+  /** The loopback port a prior login registered, reused so a strict server that
+   * pins redirect_uris still accepts a re-login after tokens are revoked. */
+  redirectPort?: number
+}
+
+/** A server name is config-controlled text; the digest keeps hostile names inside
+ * the store directory and distinct names from colliding after sanitization. */
+function storeFileFor(serverName: string): string {
+  const digest = crypto.createHash('sha256').update(serverName).digest('hex').slice(0, 8)
+  const safe =
+    serverName
+      .replace(/[^A-Za-z0-9_-]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 40) || 'server'
+  return path.join(getAgentDir(), 'mcp-oauth', `${safe}-${digest}.json`)
+}
+
+export class FileOAuthProvider implements OAuthClientProvider {
+  private readonly storePath: string
+  private data: StoredAuth
+  private port = 0
+  private readonly onRedirect: (authorizationUrl: URL) => void
+
+  constructor(serverName: string, onRedirect: (authorizationUrl: URL) => void) {
+    this.storePath = storeFileFor(serverName)
+    this.onRedirect = onRedirect
+    try {
+      this.data = JSON.parse(fs.readFileSync(this.storePath, 'utf-8'))
+    } catch {
+      this.data = {}
+    }
+  }
+
+  private persist(): void {
+    fs.mkdirSync(path.dirname(this.storePath), { recursive: true })
+    fs.writeFileSync(this.storePath, JSON.stringify(this.data), { mode: 0o600 })
+  }
+
+  /** The port a prior login registered, so a re-login can bind the same one. */
+  savedRedirectPort(): number | undefined {
+    return this.data.redirectPort
+  }
+
+  /** Record the loopback port the callback server actually bound; the redirect
+   * URL and the registered redirect_uri both derive from it. */
+  bindRedirectPort(port: number): void {
+    this.port = port
+    if (this.data.redirectPort !== port) {
+      this.data.redirectPort = port
+      this.persist()
+    }
+  }
+
+  get redirectUrl(): string {
+    return `http://127.0.0.1:${this.port}/callback`
+  }
+
+  get clientMetadata(): OAuthClientMetadata {
+    return {
+      client_name: 'pi-code',
+      redirect_uris: [this.redirectUrl],
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      // A local CLI is a public client; PKCE carries the proof instead of a secret.
+      token_endpoint_auth_method: 'none',
+    }
+  }
+
+  clientInformation(): OAuthClientInformationMixed | undefined {
+    return this.data.client
+  }
+
+  saveClientInformation(client: OAuthClientInformationMixed): void {
+    this.data.client = client
+    this.persist()
+  }
+
+  tokens(): OAuthTokens | undefined {
+    return this.data.tokens
+  }
+
+  saveTokens(tokens: OAuthTokens): void {
+    this.data.tokens = tokens
+    this.persist()
+  }
+
+  hasTokens(): boolean {
+    return this.data.tokens !== undefined
+  }
+
+  redirectToAuthorization(authorizationUrl: URL): void {
+    this.onRedirect(authorizationUrl)
+  }
+
+  saveCodeVerifier(verifier: string): void {
+    this.data.verifier = verifier
+    this.persist()
+  }
+
+  codeVerifier(): string {
+    if (!this.data.verifier) throw new Error('no code verifier saved for this authorization')
+    return this.data.verifier
+  }
+}
+
+/** A one-shot loopback listener for the authorization redirect. Loopback redirect
+ * URIs are the RFC 8252 pattern for native apps. A preferred port (from a prior
+ * login) is tried first so a re-login keeps the registered redirect_uri; if it is
+ * taken, an ephemeral port is used. */
+export async function startCallbackServer(preferredPort?: number): Promise<{ server: http.Server; port: number }> {
+  const server = http.createServer()
+  const listen = (port: number): Promise<void> => new Promise((resolve, reject) => server.listen(port, '127.0.0.1', resolve).once('error', reject))
+  try {
+    await listen(preferredPort ?? 0)
+  } catch {
+    await listen(0)
+  }
+  return { server, port: (server.address() as { port: number }).port }
+}
+
+export function waitForAuthCode(server: http.Server, timeoutMs: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`authorization timed out after ${timeoutMs}ms`)), timeoutMs)
+    server.on('request', (request, response) => {
+      const url = new URL(request.url ?? '/', 'http://127.0.0.1')
+      const code = url.searchParams.get('code')
+      const error = url.searchParams.get('error')
+      response.writeHead(200, { 'content-type': 'text/html' })
+      response.end('<html><body>pi-code: you can close this tab and return to the terminal.</body></html>')
+      clearTimeout(timer)
+      if (code) resolve(code)
+      else reject(new Error(`authorization failed: ${error ?? 'no code in redirect'} ${url.searchParams.get('error_description') ?? ''}`.trim()))
+    })
+  })
+}
+
+/** Best-effort browser launch; the caller also surfaces the URL as text. */
+export function openBrowser(url: string): void {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
+  try {
+    spawn(command, args, { stdio: 'ignore', detached: true }).unref()
+  } catch {
+    // the notified URL is the fallback
+  }
+}

package/extensions/internal/model-complete.ts

@@ -0,0 +1,68 @@
+/**
+ * One-off, in-process model completions for extensions.
+ *
+ * pi exposes ModelRuntime.completeSimple(model, context, options), so an extension
+ * can run a single tool-less prompt through a model without spawning a subprocess
+ * (the way the subagent does) or standing up its own HTTP client. The runtime
+ * resolves auth from the same credential store the session uses, and is created
+ * once and cached. This is the shared foundation for model-backed features that
+ * Claude has and pi otherwise cannot express: WebFetch's prompt-over-page answer,
+ * a hook's `type: prompt` evaluation, and similar.
+ *
+ * Every consumer must treat a completion as best-effort: it costs a model call and
+ * can fail (no credentials, headless with no model, a provider error), so failures
+ * throw and the caller falls back to its non-model behavior.
+ */
+
+import type { Api, AssistantMessage, Context, Model, ModelsSimpleStreamOptions } from '@earendil-works/pi-ai'
+import { ModelRuntime } from '@earendil-works/pi-coding-agent'
+
+/** The completion backend: model + context -> assistant message. Overridable for tests. */
+export type CompleteFn = (model: Model<Api>, context: Context, options: ModelsSimpleStreamOptions) => Promise<AssistantMessage>
+
+let backend: Promise<CompleteFn> | null = null
+
+async function realBackend(): Promise<CompleteFn> {
+  // allowModelNetwork stays false (the default): a completion must not stall on a
+  // catalog refresh. The runtime reads the same auth/models files as the session.
+  const runtime = await ModelRuntime.create()
+  return (model, context, options) => runtime.completeSimple(model, context, options)
+}
+
+/** Replace the completion backend, or reset to the real runtime with null. Tests only. */
+export function setCompleteBackend(fn: CompleteFn | null): void {
+  backend = fn ? Promise.resolve(fn) : null
+}
+
+/** The text of an assistant message, thinking and tool calls dropped. */
+export function assistantText(message: AssistantMessage): string {
+  return message.content
+    .filter((part): part is { type: 'text'; text: string } => part.type === 'text')
+    .map((part) => part.text)
+    .join('')
+    .trim()
+}
+
+export interface CompleteOptions {
+  /** System prompt for the one-off turn. */
+  system?: string
+  /** Output cap; a summary/decision does not need the model's full budget. */
+  maxTokens?: number
+  signal?: AbortSignal
+}
+
+/**
+ * Run `prompt` through `model` as a single user turn and return the reply text.
+ * Throws on any failure so the caller can fall back; never returns a partial or a
+ * tool call, only assistant text.
+ */
+export async function completeText(model: Model<Api>, prompt: string, options: CompleteOptions = {}): Promise<string> {
+  backend ??= realBackend()
+  const complete = await backend
+  const context: Context = {
+    systemPrompt: options.system,
+    messages: [{ role: 'user', content: prompt, timestamp: Date.now() }],
+  }
+  const message = await complete(model, context, { maxTokens: options.maxTokens ?? 1024, signal: options.signal })
+  return assistantText(message)
+}

package/extensions/internal/path-rules.ts

@@ -0,0 +1,80 @@
+/**
+ * Claude's Read/Edit path-rule matching, applied to allowed-tools grants.
+ *
+ * Claude consults Read(path) and Edit(path) rules for file access, with Edit
+ * rules also governing writes. Patterns follow gitignore syntax with four anchor
+ * forms: `//abs` from the filesystem root, `~/` from home, `/` from the project
+ * root (the settings source), and bare or `./` from the current directory. As
+ * allow rules, a single-segment directory pattern anchors at cwd; a bare
+ * filename matches at any depth. `*` stays within one segment, `**` crosses
+ * directories. Matching is lexical, on resolved paths; bracket expressions are
+ * not supported and match literally, which can only over-block, never widen.
+ */
+
+import * as path from 'node:path'
+
+export interface PathAnchors {
+  cwd: string
+  projectRoot: string
+  home: string
+}
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
+
+/** One gitignore-style pattern as an anchored regular expression source. */
+export function globToRegExpSource(pattern: string): string {
+  let out = ''
+  let i = 0
+  while (i < pattern.length) {
+    const ch = pattern[i]
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        const prevSlash = i === 0 || pattern[i - 1] === '/'
+        if (prevSlash && pattern[i + 2] === '/') {
+          out += '(?:[^/]+/)*' // `**/` spans zero or more whole directories
+          i += 3
+          continue
+        }
+        out += '.*'
+        i += 2
+        continue
+      }
+      out += '[^/]*'
+      i += 1
+      continue
+    }
+    if (ch === '?') {
+      out += '[^/]'
+      i += 1
+      continue
+    }
+    out += escapeRegExp(ch)
+    i += 1
+  }
+  return out
+}
+
+/** A rule resolved to an absolute glob per its anchor form. */
+function resolveRule(rule: string, anchors: PathAnchors): string {
+  if (rule.startsWith('//')) return rule.slice(1)
+  if (rule.startsWith('~/')) return path.join(anchors.home, rule.slice(2))
+  if (rule.startsWith('/')) return path.join(anchors.projectRoot, rule.slice(1))
+  const rel = rule.startsWith('./') ? rule.slice(2) : rule
+  // A bare filename follows gitignore semantics and matches at any depth under cwd.
+  if (!rel.includes('/')) return path.join(anchors.cwd, '**', rel)
+  return path.join(anchors.cwd, rel)
+}
+
+/** 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 = path.resolve(anchors.cwd, filePath)
+  return rules.some((rule) => {
+    const trimmed = rule.trim()
+    // An empty specifier (`Read()`) matches nothing, so the tool stays blocked
+    // rather than falling open, mirroring `Bash()`.
+    if (trimmed === '') return false
+    const resolved = resolveRule(trimmed, anchors)
+    return new RegExp(`^${globToRegExpSource(resolved)}$`).test(target)
+  })
+}

package/extensions/internal/plugins.ts

@@ -0,0 +1,125 @@
+/**
+ * Discovery for installed Claude Code plugins.
+ *
+ * Marketplace installs live under ~/.claude/plugins/cache/<marketplace>/<name>/
+ * <version>/, with an optional .claude-plugin/plugin.json manifest, and are
+ * active only when `enabledPlugins` in the settings chain says true, under the
+ * bare name or the marketplace-qualified `name@marketplace`. Only an explicit
+ * true enables: Claude writes the entry on install, so a cached plugin with no
+ * entry is not one the user turned on. With no version index on disk, the
+ * newest version directory wins, matching the update-then-grace-period layout.
+ * The persistent data directory (${CLAUDE_PLUGIN_DATA}) survives updates at
+ * ~/.claude/plugins/data/<id>, id being the qualified name folded to dashes.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+export interface InstalledPlugin {
+  name: string
+  /** The version directory: ${CLAUDE_PLUGIN_ROOT}. */
+  root: string
+  /** ${CLAUDE_PLUGIN_DATA}; may not exist yet. */
+  dataDir: string
+  manifest: Record<string, unknown>
+  /** Resolved `pluginConfigs[id].options` values, exposed as `${user_config.KEY}`. */
+  userConfig?: Record<string, string>
+}
+
+function readJson(file: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
+    return parsed !== null && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+function listDirs(dir: string): string[] {
+  try {
+    return fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+  } catch {
+    return []
+  }
+}
+
+/** Version directories sort numerically segment-wise, so 1.10.0 beats 1.9.0. */
+function newestVersion(versions: string[]): string | undefined {
+  return [...versions].sort((a, b) => a.localeCompare(b, 'en', { numeric: true })).at(-1)
+}
+
+/** The enablement map, later files winning per key, as settings scopes merge. */
+function enabledMap(settingsFiles: string[]): Record<string, boolean> {
+  const merged: Record<string, boolean> = {}
+  for (const file of settingsFiles) {
+    const entry = readJson(file).enabledPlugins
+    if (entry === null || typeof entry !== 'object') continue
+    for (const [name, value] of Object.entries(entry)) {
+      if (typeof value === 'boolean') merged[name] = value
+    }
+  }
+  return merged
+}
+
+/** `pluginConfigs[id].options` per plugin id, later files winning per key. */
+function pluginConfigsMap(settingsFiles: string[]): Record<string, Record<string, string>> {
+  const merged: Record<string, Record<string, string>> = {}
+  for (const file of settingsFiles) {
+    const entry = readJson(file).pluginConfigs
+    if (entry === null || typeof entry !== 'object') continue
+    for (const [id, config] of Object.entries(entry)) {
+      const options = (config as Record<string, unknown>)?.options
+      if (options === null || typeof options !== 'object') continue
+      const values = merged[id] ?? {}
+      for (const [key, value] of Object.entries(options)) {
+        if (typeof value === 'string') values[key] = value
+        else if (typeof value === 'number' || typeof value === 'boolean') values[key] = String(value)
+      }
+      merged[id] = values
+    }
+  }
+  return merged
+}
+
+/**
+ * Enabled plugins from the cache. Enablement is decided by the user's own
+ * settings only: plugins install to the user's machine and carry code (hook
+ * scripts, MCP server commands), so a checked-out repo must not be able to flip
+ * which of them run. `extraSettingsFiles`, when given, are additional
+ * user-controlled settings sources, not project files.
+ */
+export function installedPlugins(home: string, extraSettingsFiles: string[] = []): InstalledPlugin[] {
+  const cacheDir = path.join(home, '.claude', 'plugins', 'cache')
+  const settingsFiles = [path.join(home, '.claude', 'settings.json'), ...extraSettingsFiles]
+  const enabled = enabledMap(settingsFiles)
+  const configs = pluginConfigsMap(settingsFiles)
+  const plugins: InstalledPlugin[] = []
+  for (const marketplace of listDirs(cacheDir)) {
+    for (const pluginDir of listDirs(path.join(cacheDir, marketplace))) {
+      const qualified = `${pluginDir}@${marketplace}`
+      const state = enabled[qualified] ?? enabled[pluginDir]
+      if (state !== true) continue
+      const version = newestVersion(listDirs(path.join(cacheDir, marketplace, pluginDir)))
+      if (!version) continue
+      const root = path.join(cacheDir, marketplace, pluginDir, version)
+      const manifest = readJson(path.join(root, '.claude-plugin', 'plugin.json'))
+      const name = typeof manifest.name === 'string' && manifest.name.length > 0 ? manifest.name : pluginDir
+      const id = qualified.replace(/[^A-Za-z0-9]+/g, '-')
+      const userConfig = configs[qualified] ?? configs[pluginDir] ?? configs[name]
+      plugins.push({ name, root, dataDir: path.join(home, '.claude', 'plugins', 'data', id), manifest, ...(userConfig ? { userConfig } : {}) })
+    }
+  }
+  return plugins
+}
+
+/** The two plugin path variables, textually substituted into plugin-shipped
+ * config (hook commands, MCP server definitions, command bodies). */
+export function substitutePluginVars(value: string, plugin: InstalledPlugin): string {
+  return value
+    .replaceAll('${CLAUDE_PLUGIN_ROOT}', plugin.root)
+    .replaceAll('${CLAUDE_PLUGIN_DATA}', plugin.dataDir)
+    .replace(/\$\{user_config\.([A-Za-z0-9_]+)\}/g, (_, key: string) => plugin.userConfig?.[key] ?? '')
+}

package/extensions/internal/project-approval.ts

@@ -21,6 +21,8 @@ import * as fs from 'node:fs'
 import * as path from 'node:path'
 import { getAgentDir, hasTrustRequiringProjectResources, ProjectTrustStore } from '@earendil-works/pi-coding-agent'
 
+import { ROOT_MARKERS } from './project-root.js'
+
 /** Project files pi-code acts on that pi's own trust check does not look for. */
 const CLAUDE_SHAPED = [
   path.join('.claude', 'settings.json'),
@@ -37,9 +39,6 @@ const CLAUDE_SHAPED = [
   path.join('.pi', 'agents'),
 ]
 
-/** Markers that end the upward walk, matching the subagent's own discovery bound. */
-const ROOT_MARKERS = ['.git', 'package.json']
-
 /** Claude-shaped config anywhere between `cwd` and the repository root.
  *
  * The walk matters: agent discovery already searches upward, so starting pi in a

package/extensions/internal/project-root.ts

@@ -0,0 +1,78 @@
+/**
+ * Upward search for project configuration, shared across extensions.
+ *
+ * Claude anchors project config (.claude/*, .mcp.json, CLAUDE.local.md) at the
+ * project root, so a session started in a subdirectory must still find it. The
+ * walk runs from cwd up to the repository root and no further: without the bound,
+ * config planted in a world-writable ancestor such as /tmp would be offered to
+ * every session beneath it. With no project marker the extent is unknown, so only
+ * cwd is considered. The project-approval walk uses the same markers, so whatever
+ * these find is exactly what that walk gated.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+/** Project root markers ending the walk. `.git` is a file in worktrees and submodules. */
+export const ROOT_MARKERS = ['.git', 'package.json']
+
+/** Project root at or above `from`, or undefined when no marker is found. */
+export function repoRoot(from: string): string | undefined {
+  let currentDir = from
+  while (true) {
+    if (ROOT_MARKERS.some((marker) => fs.existsSync(path.join(currentDir, marker)))) 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)
+  } catch {
+    return null
+  }
+}
+
+function findNearest(cwd: string, relative: string, wantDir: boolean): string | null {
+  const boundary = repoRoot(cwd) ?? cwd
+  let currentDir = cwd
+  while (true) {
+    const candidate = path.join(currentDir, relative)
+    const stat = statOf(candidate)
+    if (stat && (wantDir ? stat.isDirectory() : stat.isFile())) return candidate
+
+    if (currentDir === boundary) return null
+    const parentDir = path.dirname(currentDir)
+    if (parentDir === currentDir) return null
+    currentDir = parentDir
+  }
+}
+
+/** Nearest `relative` directory at or above `cwd`, stopping at the repository root. */
+export function findNearestDir(cwd: string, relative: string): string | null {
+  return findNearest(cwd, relative, true)
+}
+
+/** Nearest `relative` file at or above `cwd`, stopping at the repository root. */
+export function findNearestFile(cwd: string, relative: string): string | null {
+  return findNearest(cwd, relative, false)
+}
+
+/** 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 found: string[] = []
+  let currentDir = cwd
+  while (true) {
+    const candidate = path.join(currentDir, relative)
+    if (statOf(candidate)?.isFile()) found.push(candidate)
+    if (currentDir === boundary) break
+    const parentDir = path.dirname(currentDir)
+    if (parentDir === currentDir) break
+    currentDir = parentDir
+  }
+  return found.reverse()
+}

package/extensions/internal/shell-split.ts

@@ -0,0 +1,65 @@
+/**
+ * Quote-aware splitting of a shell command into its top-level segments.
+ *
+ * Shared by plan mode's bash guard and the commands extension's allowed-tools
+ * scope enforcement: both vet each subcommand on its own, and both refuse to
+ * guess when the shell could be hiding another command.
+ */
+
+// The shell can hide an arbitrary command inside any of these, so callers refuse
+// such a command outright rather than parse it.
+const SUBSTITUTION = /\$\(|`|<\(|>\(/
+
+export const hasSubstitution = (command: string): boolean => SUBSTITUTION.test(command)
+
+/** Length of the separator at `i`, or 0 when there is none. */
+function separatorAt(command: string, i: number): number {
+  const pair = command.slice(i, i + 2)
+  if (pair === '&&' || pair === '||' || pair === '|&') return 2
+  const ch = command[i]
+  return ch === ';' || ch === '|' || ch === '&' || ch === '\n' ? 1 : 0
+}
+
+/**
+ * Split on the shell separators Claude Code documents (`&&`, `||`, `;`, `|`, `|&`, `&`,
+ * newline) so every subcommand is checked on its own, ignoring separators inside quotes:
+ * `grep 'a|b'` is one read, not a pipe. Returns nothing on an unbalanced quote, which
+ * fails the caller closed rather than guessing at the intended split.
+ *
+ * A shell AST would be exact; this is the honest approximation for a quoting-only concern.
+ */
+export function splitSegments(command: string): string[] {
+  const segments: string[] = []
+  let current = ''
+  let quote: "'" | '"' | undefined
+
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i]
+    if (quote !== undefined) {
+      current += ch
+      if (ch === quote) quote = undefined
+      continue
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch
+      current += ch
+      continue
+    }
+    if (ch === '\\' && i + 1 < command.length) {
+      current += ch + command[++i]
+      continue
+    }
+    const separator = separatorAt(command, i)
+    if (separator > 0) {
+      segments.push(current)
+      current = ''
+      i += separator - 1
+      continue
+    }
+    current += ch
+  }
+
+  if (quote !== undefined) return []
+  segments.push(current)
+  return segments.map((segment) => segment.trim()).filter(Boolean)
+}