pi-better-btw-plus 1.0.0

package/prompts/lane-reminder-base.md

@@ -0,0 +1 @@
+🚧 Lane blocked: `{{tool}}` is not available in this side chat. You are the btw side chat — a quick-question lane parallel to the main agent; the main line is the main agent's job. Answer the latest user message only, with read-only tools (read/grep/find/ls + allowlisted tools). If a write is genuinely needed, tell the user to switch to edit mode (Ctrl+T).

package/prompts/lane-reminder-escalated.md

@@ -0,0 +1 @@
+🚧 You have now attempted out-of-lane tools {{count}} times this turn. Stop trying to write or execute. Answer the latest user message with read-only tools, or report back that you cannot.

package/srcs/clipboard-read.ts

@@ -0,0 +1,339 @@
+/**
+ * Clipboard reader (D3, issue #4): read plain text from the system clipboard
+ * with an injected platform-channel matrix and level-by-level fallback.
+ *
+ * The write side is pi's own `copyToClipboard` (public export); the read side
+ * is self-built because `readClipboardText` is not re-exported from the
+ * package entry. Each platform maps to a primary channel:
+ *
+ *   - win32  → PowerShell `Get-Clipboard -Raw` (same channel family as pi's
+ *     clipboard-image reader), then an OSC 52 query;
+ *   - darwin → `pbpaste`, then an OSC 52 query;
+ *   - linux  → OSC 52 query (`\x1b]52;c;?\x07`, read the reply).
+ *
+ * Channels are injected functions, so tests mock success / fallback /
+ * all-fail without touching the host clipboard. The reader never throws:
+ * a broken channel falls through to the next one and total failure resolves
+ * to `{ ok: false, reason: "unavailable" }` — whether to surface a hint is
+ * the caller's decision.
+ */
+import { spawnSync } from "node:child_process";
+
+/**
+ * Outcome of reading the system clipboard: text, an explicitly empty
+ * clipboard (a channel ran and saw nothing), or no usable channel at all.
+ * The empty/unavailable distinction lets callers show a reason-specific
+ * hint ("Clipboard is empty" vs "Clipboard read failed").
+ */
+export type ClipboardReadOutcome =
+  | { ok: true; text: string }
+  | { ok: false; reason: "empty" | "unavailable" };
+
+/** A single clipboard read channel. */
+export interface ClipboardReadChannel {
+  /** Channel identity for diagnostics and ordering assertions. */
+  readonly name: string;
+  /**
+   * Read plain text. Resolve `{ ok: false, reason: "empty" }` when the
+   * channel ran and found the clipboard empty, `unavailable` when it could
+   * not run at all (tool missing / non-zero exit / timeout / no reply).
+   */
+  readonly read: () => Promise<ClipboardReadOutcome>;
+}
+
+/** Result of running one subprocess-based channel. */
+export interface ExecResult {
+  ok: boolean;
+  stdout: string;
+}
+
+export interface ExecOptions {
+  timeoutMs: number;
+  maxBuffer: number;
+  env?: NodeJS.ProcessEnv;
+}
+
+/** Injected subprocess runner (tests replace with a fake). */
+export type ExecFn = (
+  command: string,
+  args: readonly string[],
+  options: ExecOptions,
+) => ExecResult;
+
+/** Default subprocess runner: synchronous, mirrors pi's `runCommand`. */
+export function defaultExec(
+  command: string,
+  args: readonly string[],
+  options: ExecOptions,
+): ExecResult {
+  try {
+    const result = spawnSync(command, [...args], {
+      encoding: "utf8",
+      timeout: options.timeoutMs,
+      maxBuffer: options.maxBuffer,
+      env: options.env,
+    });
+    if (result.error) return { ok: false, stdout: "" };
+    if (result.status !== 0) return { ok: false, stdout: "" };
+    return { ok: true, stdout: result.stdout };
+  } catch {
+    return { ok: false, stdout: "" };
+  }
+}
+
+/**
+ * Try channels in order and return the first usable outcome. A channel that
+ * throws is skipped like one that reports unavailable; an explicitly empty
+ * clipboard is a definitive answer and stops the cascade — the reader
+ * never throws.
+ */
+export async function readClipboardText(
+  channels: readonly ClipboardReadChannel[],
+): Promise<ClipboardReadOutcome> {
+  for (const channel of channels) {
+    try {
+      const outcome = await channel.read();
+      if (outcome.ok) return outcome;
+      if (outcome.reason === "empty") return outcome;
+    } catch {
+      // Fall through to the next channel.
+    }
+  }
+  return { ok: false, reason: "unavailable" };
+}
+
+/** Strip the single trailing newline CLI tools append to their output. */
+function stripOneTrailingNewline(text: string): string {
+  if (text.endsWith("\r\n")) return text.slice(0, -2);
+  if (text.endsWith("\n")) return text.slice(0, -1);
+  return text;
+}
+
+const DEFAULT_EXEC_TIMEOUT_MS = 5000; // pi's PowerShell channel uses 5s too
+const DEFAULT_MAX_BUFFER_BYTES = 50 * 1024 * 1024;
+
+export interface CommandChannelOptions {
+  /** Subprocess runner override (tests). Defaults to {@link defaultExec}. */
+  exec?: ExecFn;
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+  maxBuffer?: number;
+}
+
+/**
+ * PowerShell channel: `powershell.exe -NoProfile -Command "Get-Clipboard
+ * -Raw"`, mirroring pi's clipboard-image PowerShell channel family. The
+ * `-Raw` flag preserves the exact text (no extra newline), and the output
+ * encoding is pinned to UTF-8 because the text travels over the console
+ * pipe (pi's image reader sidesteps this by writing a temp file).
+ */
+const PS_GET_CLIPBOARD_SCRIPT =
+  "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; Get-Clipboard -Raw";
+
+/** Shared shape of the subprocess-based channels: run → strip → outcome. */
+function makeCommandChannel(
+  name: string,
+  command: string,
+  args: readonly string[],
+  options: CommandChannelOptions,
+): ClipboardReadChannel {
+  const exec = options.exec ?? defaultExec;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS;
+  const maxBuffer = options.maxBuffer ?? DEFAULT_MAX_BUFFER_BYTES;
+  return {
+    name,
+    async read() {
+      let result: ExecResult;
+      try {
+        result = exec(command, args, { timeoutMs, maxBuffer, env: options.env });
+      } catch {
+        return { ok: false, reason: "unavailable" };
+      }
+      if (!result.ok) return { ok: false, reason: "unavailable" };
+      const text = stripOneTrailingNewline(result.stdout);
+      // An exit-0 empty output means the clipboard holds no text.
+      return text.length > 0
+        ? { ok: true, text }
+        : { ok: false, reason: "empty" };
+    },
+  };
+}
+
+/**
+ * PowerShell channel: `powershell.exe -NoProfile -Command "Get-Clipboard
+ * -Raw"`, mirroring pi's clipboard-image PowerShell channel family. The
+ * `-Raw` flag preserves the exact text (no extra newline), and the output
+ * encoding is pinned to UTF-8 because the text travels over the console
+ * pipe (pi's image reader sidesteps this by writing a temp file).
+ */
+export function makePowerShellChannel(
+  options: CommandChannelOptions = {},
+): ClipboardReadChannel {
+  return makeCommandChannel(
+    "powershell",
+    "powershell.exe",
+    ["-NoProfile", "-Command", PS_GET_CLIPBOARD_SCRIPT],
+    options,
+  );
+}
+
+/** macOS channel: `pbpaste` (adds a trailing newline the strip removes). */
+export function makePbpasteChannel(
+  options: CommandChannelOptions = {},
+): ClipboardReadChannel {
+  return makeCommandChannel("pbpaste", "pbpaste", [], options);
+}
+
+/** OSC 52 clipboard query: query the clipboard (c = clipboard, ? = read). */
+export const OSC52_QUERY = "\x1b]52;c;?\x07";
+
+/** Terminal reply envelope: `\x1b]52;c;<base64>` ended by BEL or ST. */
+const OSC52_REPLY_RE = /\x1b\]52;c;([^\x07\x1b]*)(?:\x07|\x1b\\)/;
+
+/** Base64 payload guard (terminal replies are always well-formed). */
+const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+
+/** Decode an OSC 52 base64 payload; null for empty / echoed / malformed. */
+export function decodeOsc52Payload(payload: string): string | null {
+  if (payload.length === 0 || payload === "?" || !BASE64_RE.test(payload)) {
+    return null;
+  }
+  try {
+    return Buffer.from(payload, "base64").toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract and decode the text from a raw OSC 52 reply. Accepts both BEL
+ * (`\x07`) and ST (`ESC \`) terminators, and replies that arrive split
+ * across stdin chunks (the regex matches once the sequence is complete).
+ * Returns null for empty / echoed-query / malformed replies.
+ */
+export function parseOsc52Reply(raw: string): string | null {
+  const match = OSC52_REPLY_RE.exec(raw);
+  if (!match) return null;
+  const text = decodeOsc52Payload(match[1]);
+  return text && text.length > 0 ? text : null;
+}
+
+export interface Osc52ChannelOptions {
+  /** Query writer override (tests). Defaults to `process.stdout.write`. */
+  write?: (sequence: string) => void;
+  /**
+   * Reply reader override (tests). Defaults to a best-effort
+   * `process.stdin` listener with a timeout. The overlay integration
+   * (right-click paste, C2) may supply its own reader that intercepts the
+   * reply before pi-tui's StdinBuffer sees it.
+   */
+  readReply?: (timeoutMs: number) => Promise<string | null>;
+  timeoutMs?: number;
+}
+
+const OSC52_READ_TIMEOUT_MS = 2000;
+
+/** Best-effort default: buffer raw stdin until the reply completes or the
+ * timeout elapses (terminals without OSC 52 query support never reply). */
+function defaultReadReply(timeoutMs: number): Promise<string | null> {
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    if (!stdin || typeof stdin.on !== "function") {
+      resolve(null);
+      return;
+    }
+    let buffer = "";
+    const timer = setTimeout(
+      () => finish(buffer.length > 0 ? buffer : null),
+      timeoutMs,
+    );
+    function onData(chunk: string | Buffer): void {
+      buffer += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk;
+      if (OSC52_REPLY_RE.test(buffer)) finish(buffer);
+    }
+    function finish(value: string | null): void {
+      clearTimeout(timer);
+      stdin.removeListener("data", onData);
+      resolve(value);
+    }
+    stdin.on("data", onData);
+    if (stdin.isPaused && stdin.isPaused()) stdin.resume();
+  });
+}
+
+/**
+ * OSC 52 query channel: write the query, read and decode the reply. A
+ * missing/unparsable reply is reported `unavailable` (the terminal either
+ * does not answer queries or the clipboard is empty — OSC 52 cannot tell
+ * the two apart, so callers treat it as a failed read).
+ */
+export function makeOsc52Channel(
+  options: Osc52ChannelOptions = {},
+): ClipboardReadChannel {
+  const write =
+    options.write ?? ((sequence: string) => process.stdout.write(sequence));
+  const readReply = options.readReply ?? defaultReadReply;
+  const timeoutMs = options.timeoutMs ?? OSC52_READ_TIMEOUT_MS;
+  return {
+    name: "osc52",
+    async read() {
+      // Attach the reply reader before sending the query so an immediate
+      // reply is not missed.
+      const replyPromise = readReply(timeoutMs);
+      write(OSC52_QUERY);
+      const raw = await replyPromise;
+      if (raw === null) return { ok: false, reason: "unavailable" };
+      const text = parseOsc52Reply(raw);
+      return text === null
+        ? { ok: false, reason: "unavailable" }
+        : { ok: true, text };
+    },
+  };
+}
+
+export interface PlatformChannelsOptions {
+  /** Platform override (tests). Defaults to `process.platform`. */
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  exec?: ExecFn;
+  write?: (sequence: string) => void;
+  readReply?: (timeoutMs: number) => Promise<string | null>;
+}
+
+/**
+ * The per-platform channel matrix (primary first, then fallbacks). win32 /
+ * darwin lead with their native tool and fall back to an OSC 52 query;
+ * linux (and unknown platforms) query OSC 52 directly — mirroring the
+ * write-side cascade where OSC 52 is the universal last resort.
+ */
+export function buildPlatformChannels(
+  options: PlatformChannelsOptions = {},
+): ClipboardReadChannel[] {
+  const osc52 = makeOsc52Channel({
+    write: options.write,
+    readReply: options.readReply,
+  });
+  switch (options.platform ?? process.platform) {
+    case "win32":
+      return [
+        makePowerShellChannel({ exec: options.exec, env: options.env }),
+        osc52,
+      ];
+    case "darwin":
+      return [
+        makePbpasteChannel({ exec: options.exec, env: options.env }),
+        osc52,
+      ];
+    case "linux":
+      return [osc52];
+    default:
+      return [osc52];
+  }
+}
+
+/** Read the clipboard with the current platform's channel matrix. */
+export function readClipboardTextFromSystem(
+  options: PlatformChannelsOptions = {},
+): Promise<ClipboardReadOutcome> {
+  return readClipboardText(buildPlatformChannels(options));
+}

package/srcs/config.ts

@@ -0,0 +1,341 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import type { PromptPackManifest } from "./prompt-pack.ts";
+import type { RetryPolicy } from "./retry.ts";
+/**
+ * Layered config resolution for pi-better-btw.
+ *
+ * Sources, in increasing precedence (a layer only contributes keys it
+ * actually defines — absent/invalid keys fall through to the layer below):
+ *
+ *   1. bundle   — <extensionDir>/config.json            (shipped defaults)
+ *   2. user     — ~/.pi/agent/pi-better-btw/config.json (personal defaults)
+ *   3. project  — <cwd>/.pi/pi-better-btw/config.json   (per-project overrides)
+ *
+ * Merge semantics:
+ * - `readOnlyExtensionAllowlist` is UNIONED across layers in bundle → user →
+ *   project order (deduped, first occurrence wins). A higher layer adds tools,
+ *   it never drops the defaults shipped below it.
+ * - `readOnlyExtensionAllowlistExclude` removes names from the final list, so
+ *   a bundled default can be dropped explicitly.
+ * - `promptPack` merges per leaf key (framing / focusAnchor / each lane
+ *   reminder), higher layer wins; relative paths resolve against the layer's
+ *   own directory (so a user-level manifest may live next to the user config).
+ *
+ * Loaded fresh at every side-chat open — no caching, so edits to any layer
+ * apply on the next open (same philosophy as the prompt pack).
+ */
+
+/**
+ * Per-feature kill switches (D11). Each defaults to true; a layer only
+ * overrides the keys it defines, so a user can disable one behavior without
+ * touching the others (or the bundle defaults). Read-only here — the
+ * switches are resolved at every side-chat open, like the rest of the config.
+ */
+export interface SideChatFeatures {
+  /** Right-click copy (chat selection) / paste (editor). Default: true. */
+  rightClickCopyPaste: boolean;
+  /** Alt+M fork model picker. Default: true. */
+  modelSwitch: boolean;
+  /** Turn-level auto-retry of transient provider errors. Default: true. */
+  retry: boolean;
+}
+
+export interface SideChatConfig {
+  readOnlyExtensionAllowlist: string[];
+  promptPack: PromptPackManifest | undefined;
+  features: SideChatFeatures;
+}
+
+export interface LoadConfigOptions {
+  /** Directory of the extension bundle (base for the bundle config.json). */
+  extensionDir: string;
+  /** Current working directory; project layer is skipped when absent. */
+  cwd?: string;
+  /** User config dir override (tests). Defaults to ~/.pi/agent/pi-sidechat. */
+  userConfigDir?: string;
+  /** Surfaces config problems (invalid JSON) instead of logging to console. */
+  onWarning?: (message: string) => void;
+}
+
+export const CONFIG_SUBDIR = "pi-better-btw";
+export const USER_CONFIG_DIR = join(homedir(), ".pi", "agent", CONFIG_SUBDIR);
+/** pi's own agent config dir (home of the shared settings.json). */
+export const AGENT_CONFIG_DIR = join(homedir(), ".pi", "agent");
+
+/**
+ * Read pi's `settings.retry` budget (D8). The fork shares pi's settings files
+ * rather than re-declaring them: global <agentConfigDir>/settings.json merged
+ * with project <cwd>/.pi/settings.json (project wins per key, mirroring pi's
+ * deepMergeSettings), then the `retry` block is extracted with pi's defaults
+ * (settingsManager.getRetrySettings: enabled=true, maxRetries=3,
+ * baseDelayMs=2000). Invalid/absent files contribute nothing; a present-but-
+ * unreadable file warns instead of failing the fork.
+ */
+export interface LoadRetryPolicyOptions {
+  /** Agent config dir holding pi's global settings.json (~/.pi/agent). */
+  agentConfigDir?: string;
+  /** cwd for the project layer (<cwd>/.pi/settings.json); skipped when absent. */
+  cwd?: string;
+  onWarning?: (message: string) => void;
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Deep merge like pi's deepMergeSettings: nested plain objects merge, arrays/others replace. */
+function deepMergeSettings(
+  base: Record<string, unknown>,
+  overrides: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(overrides)) {
+    const baseValue = result[key];
+    result[key] =
+      isPlainRecord(baseValue) && isPlainRecord(value)
+        ? deepMergeSettings(baseValue, value)
+        : value;
+  }
+  return result;
+}
+
+function readSettingsFile(
+  path: string,
+  onWarning?: (message: string) => void,
+): Record<string, unknown> {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    return isPlainRecord(raw) ? raw : {};
+  } catch {
+    if (existsSync(path) && onWarning) {
+      onWarning(`pi-better-btw: ignoring invalid settings ${path}`);
+    }
+    return {};
+  }
+}
+
+export function loadRetryPolicy(options: LoadRetryPolicyOptions = {}): RetryPolicy {
+  const agentConfigDir = options.agentConfigDir ?? AGENT_CONFIG_DIR;
+  const merged = deepMergeSettings(
+    readSettingsFile(join(agentConfigDir, "settings.json"), options.onWarning),
+    options.cwd
+      ? readSettingsFile(join(options.cwd, ".pi", "settings.json"), options.onWarning)
+      : {},
+  );
+  const retry = isPlainRecord(merged.retry) ? merged.retry : {};
+  return {
+    enabled:
+      typeof retry.enabled === "boolean" ? retry.enabled : true,
+    maxRetries:
+      typeof retry.maxRetries === "number" ? retry.maxRetries : 3,
+    baseDelayMs:
+      typeof retry.baseDelayMs === "number" ? retry.baseDelayMs : 2000,
+  };
+}
+
+interface ConfigLayer {
+  readOnlyExtensionAllowlist: string[] | undefined;
+  readOnlyExtensionAllowlistExclude: string[] | undefined;
+  promptPack: PromptPackManifest | undefined;
+  /** Feature switches this layer actually defines (undefined = falls through). */
+  features: Partial<SideChatFeatures> | undefined;
+}
+
+function parseStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const names = value.filter(
+    (n): n is string => typeof n === "string" && n.length > 0,
+  );
+  return names.length > 0 ? names : undefined;
+}
+
+/** Boolean feature switch; non-boolean values are ignored (fall through). */
+function parseBoolean(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+/** Resolve a prompt-pack path against the layer's dir; non-strings stay undefined. */
+function resolvePath(value: unknown, dir: string): string | undefined {
+  if (typeof value !== "string") return undefined;
+  return isAbsolute(value) ? value : join(dir, value);
+}
+
+function parsePromptPack(
+  value: unknown,
+  dir: string,
+): PromptPackManifest | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return undefined;
+  const rec = value as Record<string, unknown>;
+  const lane = rec.laneReminders;
+  const laneRec =
+    lane && typeof lane === "object" && !Array.isArray(lane)
+      ? (lane as Record<string, unknown>)
+      : undefined;
+  return {
+    framing: resolvePath(rec.framing, dir),
+    focusAnchor: resolvePath(rec.focusAnchor, dir),
+    laneReminders: {
+      base: resolvePath(laneRec?.base, dir),
+      escalated: resolvePath(laneRec?.escalated, dir),
+      failedNote: resolvePath(laneRec?.failedNote, dir),
+      preamble: resolvePath(laneRec?.preamble, dir),
+    },
+  };
+}
+
+function parseConfigLayer(raw: unknown, dir: string): ConfigLayer {
+  const rec =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : {};
+  const rawFeatures = rec.features;
+  const featureRec =
+    rawFeatures && typeof rawFeatures === "object" && !Array.isArray(rawFeatures)
+      ? (rawFeatures as Record<string, unknown>)
+      : undefined;
+  return {
+    readOnlyExtensionAllowlist: parseStringArray(
+      rec.readOnlyExtensionAllowlist,
+    ),
+    readOnlyExtensionAllowlistExclude: parseStringArray(
+      rec.readOnlyExtensionAllowlistExclude,
+    ),
+    promptPack: parsePromptPack(rec.promptPack, dir),
+    features: featureRec
+      ? {
+          rightClickCopyPaste: parseBoolean(featureRec.rightClickCopyPaste),
+          modelSwitch: parseBoolean(featureRec.modelSwitch),
+          retry: parseBoolean(featureRec.retry),
+        }
+      : undefined,
+  };
+}
+
+/** Read one config file; absent or invalid JSON contributes nothing (with a warning). */
+function readLayer(
+  path: string,
+  dir: string,
+  onWarning?: (message: string) => void,
+): ConfigLayer {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    return parseConfigLayer(raw, dir);
+  } catch {
+    if (existsSync(path) && onWarning) {
+      // Present but unreadable: warn instead of silently ignoring a typo.
+      onWarning(`pi-better-btw: ignoring invalid config ${path}`);
+    }
+    return parseConfigLayer(undefined, dir);
+  }
+}
+
+/** Union allowlists bundle → user → project, then apply excludes. */
+function mergeAllowlists(layers: ConfigLayer[]): string[] {
+  const names: string[] = [];
+  for (const layer of layers) {
+    for (const name of layer.readOnlyExtensionAllowlist ?? []) {
+      if (!names.includes(name)) names.push(name);
+    }
+  }
+  const excluded = new Set<string>();
+  for (const layer of layers) {
+    for (const name of layer.readOnlyExtensionAllowlistExclude ?? [])
+      excluded.add(name);
+  }
+  return names.filter((name) => !excluded.has(name));
+}
+
+/** Per-leaf-key promptPack merge, higher layer wins; undefined when nothing defined. */
+function mergePromptPacks(
+  layers: ConfigLayer[],
+): PromptPackManifest | undefined {
+  const merged: PromptPackManifest = {};
+  const lane: NonNullable<PromptPackManifest["laneReminders"]> = {};
+  let defined = false;
+  for (const layer of layers) {
+    const pack = layer.promptPack;
+    if (!pack) continue;
+    if (pack.framing !== undefined) {
+      merged.framing = pack.framing;
+      defined = true;
+    }
+    if (pack.focusAnchor !== undefined) {
+      merged.focusAnchor = pack.focusAnchor;
+      defined = true;
+    }
+    const layerLane = pack.laneReminders ?? {};
+    for (const key of [
+      "base",
+      "escalated",
+      "failedNote",
+      "preamble",
+    ] as const) {
+      if (layerLane[key] !== undefined) {
+        lane[key] = layerLane[key];
+        defined = true;
+      }
+    }
+  }
+  if (Object.keys(lane).length > 0) merged.laneReminders = lane;
+  return defined ? merged : undefined;
+}
+
+/**
+ * Feature switches merge per leaf key, higher layer wins; keys no layer
+ * defines keep their default (true). A layer can disable one behavior
+ * (`"retry": false`) without re-declaring the others.
+ */
+const FEATURE_KEYS = [
+  "rightClickCopyPaste",
+  "modelSwitch",
+  "retry",
+] as const;
+function mergeFeatures(layers: ConfigLayer[]): SideChatFeatures {
+  const features: SideChatFeatures = {
+    rightClickCopyPaste: true,
+    modelSwitch: true,
+    retry: true,
+  };
+  for (const layer of layers) {
+    const layerFeatures = layer.features;
+    if (!layerFeatures) continue;
+    for (const key of FEATURE_KEYS) {
+      const value = layerFeatures[key];
+      if (value !== undefined) features[key] = value;
+    }
+  }
+  return features;
+}
+
+export function loadConfig(options: LoadConfigOptions): SideChatConfig {
+  const layers: ConfigLayer[] = [];
+  layers.push(
+    readLayer(
+      join(options.extensionDir, "config.json"),
+      options.extensionDir,
+      options.onWarning,
+    ),
+  );
+  const userConfigDir = options.userConfigDir ?? USER_CONFIG_DIR;
+  layers.push(
+    readLayer(
+      join(userConfigDir, "config.json"),
+      userConfigDir,
+      options.onWarning,
+    ),
+  );
+  if (options.cwd) {
+    const projectDir = join(options.cwd, ".pi", CONFIG_SUBDIR);
+    layers.push(
+      readLayer(join(projectDir, "config.json"), projectDir, options.onWarning),
+    );
+  }
+  return {
+    readOnlyExtensionAllowlist: mergeAllowlists(layers),
+    promptPack: mergePromptPacks(layers),
+    features: mergeFeatures(layers),
+  };
+}