@bermudi/pi-delegate 0.1.11 → 0.1.12

package/config.ts

@@ -1,13 +1,164 @@
+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 { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import {
   MAX_ASYNC_TICKETS,
   MAX_CONCURRENCY,
   OUTPUT_SPILL_TAIL_CHARS,
   OUTPUT_SPILL_THRESHOLD_CHARS,
+  VALID_THINKING,
 } from "./constants.ts";
 
+export interface AgentOverride {
+  model?: string;
+  thinking?: ThinkingLevel;
+  tools?: string[];
+}
+
+const DELEGATE_CONFIG_SOURCE = "delegate.json";
+
+/** Validate one agentOverrides entry. A malformed entry is dropped whole
+ *  (warn) rather than partially applied — a half-parsed override that
+ *  silently changes only `thinking` is worse than a loud no-op. */
+function normalizeAgentOverride(
+  raw: unknown,
+  agentName: string,
+): AgentOverride | null {
+  if (!isRecord(raw)) {
+    console.warn(
+      `[delegate] ignoring malformed agentOverrides entry for agent '${agentName}' in ${DELEGATE_CONFIG_SOURCE}: expected an object.`,
+    );
+    return null;
+  }
+
+  const result: AgentOverride = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (key === "model") {
+      if (typeof value !== "string" || value.trim().length === 0) {
+        console.warn(
+          `[delegate] ignoring malformed agentOverrides entry for agent '${agentName}' in ${DELEGATE_CONFIG_SOURCE}: model must be a nonempty string.`,
+        );
+        return null;
+      }
+      result.model = value.trim();
+    } else if (key === "thinking") {
+      if (typeof value !== "string" || !VALID_THINKING.has(value)) {
+        console.warn(
+          `[delegate] ignoring malformed agentOverrides entry for agent '${agentName}' in ${DELEGATE_CONFIG_SOURCE}: thinking must be a supported level.`,
+        );
+        return null;
+      }
+      result.thinking = value as ThinkingLevel;
+    } else if (key === "tools") {
+      if (
+        !Array.isArray(value) ||
+        value.some((tool) => typeof tool !== "string")
+      ) {
+        console.warn(
+          `[delegate] ignoring malformed agentOverrides entry for agent '${agentName}' in ${DELEGATE_CONFIG_SOURCE}: tools must be a string array.`,
+        );
+        return null;
+      }
+      result.tools = [...value];
+    } else if (key === "skills") {
+      console.warn(
+        `[delegate] ignoring unsupported skills override for agent '${agentName}' in ${DELEGATE_CONFIG_SOURCE}: per-agent skill filtering is not supported.`,
+      );
+      return null;
+    } else {
+      console.warn(
+        `[delegate] ignoring malformed agentOverrides entry for agent '${agentName}' in ${DELEGATE_CONFIG_SOURCE}: unknown field '${key}'.`,
+      );
+      return null;
+    }
+  }
+  return result;
+}
+
+/** Normalize the `agentOverrides` map (agent name → override). Keys are
+ *  trimmed; collisions after trimming keep the first entry and warn. Returns
+ *  undefined when the block is absent. */
+function normalizeAgentOverrides(
+  raw: unknown,
+): Record<string, AgentOverride> | undefined {
+  if (raw === undefined) return undefined;
+  if (!isRecord(raw)) {
+    console.warn(
+      `[delegate] ignoring malformed agentOverrides in ${DELEGATE_CONFIG_SOURCE}: expected an object.`,
+    );
+    return undefined;
+  }
+
+  // Null-prototype map so config keys such as `constructor` and `__proto__`
+  // cannot resolve to Object.prototype members during normalization.
+  const out = Object.create(null) as Record<string, AgentOverride>;
+  const seenNames = new Map<string, string>();
+  for (const [agentName, value] of Object.entries(raw)) {
+    const normalizedAgentName = agentName.trim();
+    if (normalizedAgentName.length === 0) {
+      console.warn(
+        `[delegate] ignoring malformed agentOverrides entry in ${DELEGATE_CONFIG_SOURCE}: agent name must be nonempty.`,
+      );
+      continue;
+    }
+    const previousName = seenNames.get(normalizedAgentName);
+    if (previousName !== undefined) {
+      console.warn(
+        `[delegate] ignoring duplicate agentOverrides entry in ${DELEGATE_CONFIG_SOURCE}: agent keys '${previousName}' and '${agentName}' both normalize to '${normalizedAgentName}'.`,
+      );
+      continue;
+    }
+    seenNames.set(normalizedAgentName, agentName);
+    const override = normalizeAgentOverride(value, normalizedAgentName);
+    if (override) out[normalizedAgentName] = override;
+  }
+  return out;
+}
+
+/** Normalize `agentOverridesByParentModel` (`provider/model-id` → agent →
+ *  override). Model keys are trimmed, not lowercased: they must match the
+ *  parent's exact `provider/model-id`. Returns undefined when absent. */
+function normalizeAgentOverridesByParentModel(
+  raw: unknown,
+): Record<string, Record<string, AgentOverride>> | undefined {
+  if (raw === undefined) return undefined;
+  if (!isRecord(raw)) {
+    console.warn(
+      `[delegate] ignoring malformed agentOverridesByParentModel in ${DELEGATE_CONFIG_SOURCE}: expected an object.`,
+    );
+    return undefined;
+  }
+
+  const out = Object.create(null) as Record<
+    string,
+    Record<string, AgentOverride>
+  >;
+  const seenModels = new Map<string, string>();
+  for (const [parentModel, overrides] of Object.entries(raw)) {
+    const normalizedParentModel = parentModel.trim();
+    if (normalizedParentModel.length === 0) {
+      console.warn(
+        `[delegate] ignoring malformed parent-model override in ${DELEGATE_CONFIG_SOURCE}: model key must be nonempty.`,
+      );
+      continue;
+    }
+    const previousModel = seenModels.get(normalizedParentModel);
+    if (previousModel !== undefined) {
+      console.warn(
+        `[delegate] ignoring duplicate parent-model override in ${DELEGATE_CONFIG_SOURCE}: model keys '${previousModel}' and '${parentModel}' both normalize to '${normalizedParentModel}'.`,
+      );
+      continue;
+    }
+    seenModels.set(normalizedParentModel, parentModel);
+    const inner = normalizeAgentOverrides(overrides);
+    out[normalizedParentModel] =
+      inner ?? (Object.create(null) as Record<string, AgentOverride>);
+  }
+  return out;
+}
+
 export interface TelemetryConfig {
   /** Whether to record delegate calls to the local SQLite store. Default true. */
   enabled?: boolean;
@@ -23,6 +174,172 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+function isPositiveInteger(value: unknown): value is number {
+  return (
+    typeof value === "number" &&
+    Number.isFinite(value) &&
+    Number.isInteger(value) &&
+    value > 0
+  );
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return (
+    typeof value === "number" &&
+    Number.isFinite(value) &&
+    Number.isInteger(value) &&
+    value >= 0
+  );
+}
+
+/** Validate numeric and nested-object fields before they reach the config
+ *  singleton. Malformed values in `delegate.json` must not replace a valid
+ *  snapshot with a half-parsed object that later produces `NaN` concurrency
+ *  limits and deadlocks the global semaphore. */
+function validateNumericAndNestedFields(
+  raw: Record<string, unknown>,
+): string | null {
+  if (
+    "allowUnsafeSharedWrites" in raw &&
+    typeof raw.allowUnsafeSharedWrites !== "boolean"
+  ) {
+    return `allowUnsafeSharedWrites must be a boolean; got ${JSON.stringify(
+      raw.allowUnsafeSharedWrites,
+    )}`;
+  }
+  if ("agent" in raw && raw.agent !== undefined && !isRecord(raw.agent)) {
+    return "agent must be an object";
+  }
+  if (
+    "concurrency" in raw &&
+    raw.concurrency !== undefined &&
+    !isRecord(raw.concurrency)
+  ) {
+    return "concurrency must be an object";
+  }
+  if ("retry" in raw && raw.retry !== undefined && !isRecord(raw.retry)) {
+    return "retry must be an object";
+  }
+  if ("output" in raw && raw.output !== undefined && !isRecord(raw.output)) {
+    return "output must be an object";
+  }
+
+  if (
+    "maxConcurrent" in raw &&
+    raw.maxConcurrent !== undefined &&
+    !isPositiveInteger(raw.maxConcurrent)
+  ) {
+    return `maxConcurrent must be a positive integer; got ${JSON.stringify(
+      raw.maxConcurrent,
+    )}`;
+  }
+  if (
+    "maxAsyncTickets" in raw &&
+    raw.maxAsyncTickets !== undefined &&
+    !isPositiveInteger(raw.maxAsyncTickets)
+  ) {
+    return `maxAsyncTickets must be a positive integer; got ${JSON.stringify(
+      raw.maxAsyncTickets,
+    )}`;
+  }
+  if (
+    "stallTimeoutMs" in raw &&
+    raw.stallTimeoutMs !== undefined &&
+    !isNonNegativeInteger(raw.stallTimeoutMs)
+  ) {
+    return `stallTimeoutMs must be a non-negative integer; got ${JSON.stringify(
+      raw.stallTimeoutMs,
+    )}`;
+  }
+
+  const concurrency = raw.concurrency;
+  if (concurrency) {
+    const c = concurrency as Record<string, unknown>;
+    if ("default" in c && !isPositiveInteger(c.default)) {
+      return `concurrency.default must be a positive integer; got ${JSON.stringify(
+        c.default,
+      )}`;
+    }
+    if ("providers" in c) {
+      const providers = c.providers;
+      if (!isRecord(providers)) {
+        return "concurrency.providers must be an object";
+      }
+      for (const [key, value] of Object.entries(providers)) {
+        if (!isPositiveInteger(value)) {
+          return `concurrency.providers.${key} must be a positive integer; got ${JSON.stringify(
+            value,
+          )}`;
+        }
+      }
+    }
+    if ("models" in c) {
+      const models = c.models;
+      if (!isRecord(models)) {
+        return "concurrency.models must be an object";
+      }
+      for (const [key, value] of Object.entries(models)) {
+        if (!isPositiveInteger(value)) {
+          return `concurrency.models.${key} must be a positive integer; got ${JSON.stringify(
+            value,
+          )}`;
+        }
+      }
+    }
+  }
+
+  const retry = raw.retry;
+  if (retry) {
+    const r = retry as Record<string, unknown>;
+    if (
+      "wholeTaskMaxRetries" in r &&
+      !isNonNegativeInteger(r.wholeTaskMaxRetries)
+    ) {
+      return `retry.wholeTaskMaxRetries must be a non-negative integer; got ${JSON.stringify(
+        r.wholeTaskMaxRetries,
+      )}`;
+    }
+    if (
+      "wholeTaskBaseDelayMs" in r &&
+      !isNonNegativeInteger(r.wholeTaskBaseDelayMs)
+    ) {
+      return `retry.wholeTaskBaseDelayMs must be a non-negative integer; got ${JSON.stringify(
+        r.wholeTaskBaseDelayMs,
+      )}`;
+    }
+  }
+
+  const output = raw.output;
+  if (output) {
+    const o = output as Record<string, unknown>;
+    if (
+      "spillThresholdChars" in o &&
+      !isPositiveInteger(o.spillThresholdChars)
+    ) {
+      return `output.spillThresholdChars must be a positive integer; got ${JSON.stringify(
+        o.spillThresholdChars,
+      )}`;
+    }
+    if ("spillTailChars" in o && !isNonNegativeInteger(o.spillTailChars)) {
+      return `output.spillTailChars must be a non-negative integer; got ${JSON.stringify(
+        o.spillTailChars,
+      )}`;
+    }
+  }
+
+  return null;
+}
+
+/** Return a safe positive integer from a possibly malformed config value. */
+function safePositiveInteger(value: unknown, defaultValue: number): number {
+  return isPositiveInteger(value) ? (value as number) : defaultValue;
+}
+
+/** Return a safe non-negative integer from a possibly malformed config value. */
+function safeNonNegativeInteger(value: unknown, defaultValue: number): number {
+  return isNonNegativeInteger(value) ? (value as number) : defaultValue;
+}
+
 /**
  * Validate the user-editable telemetry block at its boundary. An explicitly
  * malformed block disables telemetry rather than silently turning it on with
@@ -61,6 +378,14 @@ export interface DelegateConfig {
     /** Per-agent-type model overrides. Keys are agent names or "default". */
     [agentType: string]: string | null | undefined;
   };
+  /** Per-agent model/thinking/tools overrides (agent name → override), from
+   *  delegate.json. Applies to every non-`default` agent, including the
+   *  built-ins (`scout`/`coder`/`reviewer`) and custom agents. This is the
+   *  modern form; the legacy `agent` map above still feeds custom agents. */
+  agentOverrides?: Record<string, AgentOverride>;
+  /** Parent-model-scoped overrides keyed by the parent's exact
+   *  `provider/model-id`. Win over `agentOverrides` on a key match. */
+  agentOverridesByParentModel?: Record<string, Record<string, AgentOverride>>;
   /** Per-model and per-provider concurrency limits. */
   concurrency: {
     /** Default concurrency limit for unspecified models. */
@@ -76,6 +401,9 @@ export interface DelegateConfig {
   maxAsyncTickets?: number;
   /** Maximum inactivity before cooperative stall cancellation is requested (0 disables). */
   stallTimeoutMs?: number;
+  /** Operator-only escape hatch for overlapping shared writers. Not exposed
+   *  through the model-facing tool schema. Default false. */
+  allowUnsafeSharedWrites?: boolean;
   /** Whole-task transient-error retry settings. */
   retry?: {
     /** Max whole-task retries after the initial attempt (0 = no retry). */
@@ -99,8 +427,12 @@ export interface DelegateConfig {
   };
 }
 
-const DELEGATE_CONFIG_DIR = path.join(os.homedir(), ".pi", "agent");
-const DELEGATE_CONFIG_PATH = path.join(DELEGATE_CONFIG_DIR, "delegate.json");
+/** Resolved lazily (not at module scope) so the path follows the live
+ *  `os.homedir()` — the test suite swaps homedir via `mock.module`, and an
+ *  eagerly-bound path would keep reading the developer's real config. */
+function delegateConfigPath(): string {
+  return path.join(os.homedir(), ".pi", "agent", "delegate.json");
+}
 
 function normalizeProviderExtensions(
   raw: unknown,
@@ -158,6 +490,7 @@ const DEFAULT_DELEGATE_CONFIG: DelegateConfig = {
   concurrency: { default: MAX_CONCURRENCY },
   maxConcurrent: MAX_CONCURRENCY,
   stallTimeoutMs: 15 * 60 * 1000,
+  allowUnsafeSharedWrites: false,
   retry: {
     wholeTaskMaxRetries: 3,
     wholeTaskBaseDelayMs: 1_000,
@@ -181,6 +514,72 @@ let __delegateConfig: DelegateConfig = {
 };
 let stallTimeoutOverrideForTesting: number | undefined;
 
+type ReadConfigResult =
+  | { status: "ok"; config: DelegateConfig }
+  | { status: "missing" }
+  | { status: "error"; error: unknown };
+
+/** Read and normalize delegate.json from disk. Distinguishes a missing file
+ *  (deliberate deletion) from parse/read errors so reload can keep the prior
+ *  valid snapshot instead of silently installing defaults. */
+function readDelegateConfigFromDisk(): ReadConfigResult {
+  try {
+    const raw = fs.readFileSync(delegateConfigPath(), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {
+        status: "error",
+        error: new Error("top-level value is not an object"),
+      };
+    }
+    const numericError = validateNumericAndNestedFields(
+      parsed as Record<string, unknown>,
+    );
+    if (numericError) {
+      return {
+        status: "error",
+        error: new Error(numericError),
+      };
+    }
+    // Merge with defaults so new fields are always present
+    return {
+      status: "ok",
+      config: {
+        ...DEFAULT_DELEGATE_CONFIG,
+        ...parsed,
+        agent: { ...DEFAULT_DELEGATE_CONFIG.agent, ...(parsed.agent ?? {}) },
+        concurrency: {
+          ...DEFAULT_DELEGATE_CONFIG.concurrency,
+          ...(parsed.concurrency ?? {}),
+        },
+        retry: { ...DEFAULT_DELEGATE_CONFIG.retry, ...(parsed.retry ?? {}) },
+        providerExtensions: normalizeProviderExtensions(
+          parsed.providerExtensions,
+        ),
+        agentOverrides: normalizeAgentOverrides(parsed.agentOverrides),
+        agentOverridesByParentModel: normalizeAgentOverridesByParentModel(
+          parsed.agentOverridesByParentModel,
+        ),
+        telemetry: normalizeTelemetryConfig(parsed.telemetry),
+        output: {
+          ...DEFAULT_DELEGATE_CONFIG.output,
+          ...(parsed.output ?? {}),
+        },
+      } as DelegateConfig,
+    };
+  } catch (error) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return { status: "missing" };
+    }
+    return { status: "error", error };
+  }
+}
+
 /** Read delegate config from disk. Returns defaults if file missing or corrupt.
  *
  *  The returned `providerExtensions` is the *user-only* view — exactly what the
@@ -191,30 +590,63 @@ let stallTimeoutOverrideForTesting: number | undefined;
  *  distinguish "the user listed this" from "this is a shipped default" by
  *  config presence rather than string identity. */
 export function loadDelegateConfig(): DelegateConfig {
-  try {
-    const raw = fs.readFileSync(DELEGATE_CONFIG_PATH, "utf-8");
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-      return structuredClone(DEFAULT_DELEGATE_CONFIG);
-    // Merge with defaults so new fields are always present
-    return {
-      ...DEFAULT_DELEGATE_CONFIG,
-      ...parsed,
-      agent: { ...DEFAULT_DELEGATE_CONFIG.agent, ...(parsed.agent ?? {}) },
-      concurrency: {
-        ...DEFAULT_DELEGATE_CONFIG.concurrency,
-        ...(parsed.concurrency ?? {}),
-      },
-      retry: { ...DEFAULT_DELEGATE_CONFIG.retry, ...(parsed.retry ?? {}) },
-      providerExtensions: normalizeProviderExtensions(
-        parsed.providerExtensions,
-      ),
-      telemetry: normalizeTelemetryConfig(parsed.telemetry),
-      output: { ...DEFAULT_DELEGATE_CONFIG.output, ...(parsed.output ?? {}) },
-    } as DelegateConfig;
-  } catch {
+  const result = readDelegateConfigFromDisk();
+  if (result.status === "error") {
+    console.warn(
+      `[delegate] could not load ${DELEGATE_CONFIG_SOURCE}: ${
+        result.error instanceof Error
+          ? result.error.message
+          : String(result.error)
+      }; using defaults.`,
+    );
     return structuredClone(DEFAULT_DELEGATE_CONFIG);
   }
+  if (result.status === "missing")
+    return structuredClone(DEFAULT_DELEGATE_CONFIG);
+  return result.config;
+}
+
+/** Clone a config while retaining the null-prototype override maps.
+ *
+ * `structuredClone` deliberately preserves data, not object prototypes. That
+ * is normally useful, but these maps are a trust boundary: an inherited
+ * `constructor` or `toString` must not look like a configured agent.
+ */
+function cloneDelegateConfig(config: DelegateConfig): DelegateConfig {
+  const clone = structuredClone(config);
+
+  if (clone.agentOverrides) {
+    clone.agentOverrides = cloneNullPrototypeMap(clone.agentOverrides);
+  }
+  if (clone.agentOverridesByParentModel) {
+    const parentModels = cloneNullPrototypeMap(
+      clone.agentOverridesByParentModel,
+    );
+    for (const [parentModel, overrides] of Object.entries(parentModels)) {
+      parentModels[parentModel] = cloneNullPrototypeMap(overrides);
+    }
+    clone.agentOverridesByParentModel = parentModels;
+  }
+
+  return clone;
+}
+
+function cloneNullPrototypeMap<T>(map: Record<string, T>): Record<string, T> {
+  const clone = Object.create(null) as Record<string, T>;
+  for (const [key, value] of Object.entries(map)) {
+    clone[key] = value;
+  }
+  return clone;
+}
+
+/** Return an immutable snapshot of the current delegate configuration.
+ *
+ *  Async tickets and long-lived task runners capture this at dispatch time so
+ *  a later `delegate.json` edit cannot retroactively change an in-flight
+ *  batch's retry limits, stall timeout, output-spill bounds, or provider
+ *  extension allowlist. */
+export function getDelegateConfigSnapshot(): DelegateConfig {
+  return cloneDelegateConfig(__delegateConfig);
 }
 
 /** Initialize module config from disk. Called once at extension load. */
@@ -257,9 +689,21 @@ export function _setStallTimeoutForTesting(
 export function _setDelegateConfigForTesting(
   config: Partial<DelegateConfig> = {},
 ): void {
+  const numericError = validateNumericAndNestedFields(
+    config as Record<string, unknown>,
+  );
+  if (numericError) {
+    throw new Error(`[delegate] _setDelegateConfigForTesting: ${numericError}`);
+  }
   __delegateConfig = {
     ...DEFAULT_DELEGATE_CONFIG,
     ...config,
+    maxConcurrent:
+      config.maxConcurrent ?? DEFAULT_DELEGATE_CONFIG.maxConcurrent,
+    maxAsyncTickets:
+      config.maxAsyncTickets ?? DEFAULT_DELEGATE_CONFIG.maxAsyncTickets,
+    stallTimeoutMs:
+      config.stallTimeoutMs ?? DEFAULT_DELEGATE_CONFIG.stallTimeoutMs,
     agent: {
       ...DEFAULT_DELEGATE_CONFIG.agent,
       ...(config.agent ?? {}),
@@ -273,6 +717,10 @@ export function _setDelegateConfigForTesting(
       ...(config.retry ?? {}),
     },
     providerExtensions: normalizeProviderExtensions(config.providerExtensions),
+    agentOverrides: normalizeAgentOverrides(config.agentOverrides),
+    agentOverridesByParentModel: normalizeAgentOverridesByParentModel(
+      config.agentOverridesByParentModel,
+    ),
     telemetry: normalizeTelemetryConfig(config.telemetry),
     output: {
       ...DEFAULT_DELEGATE_CONFIG.output,
@@ -316,6 +764,33 @@ export function getSubagentProviderExtensionsForProvider(
     : [];
 }
 
+/** Stable signature for the provider-scoped extension allowlist that applies
+ *  to a given model provider. Used as a pool compatibility key so a
+ *  `delegate.json` edit that revokes or changes an allowlisted extension does
+ *  not silently reuse a pooled session whose runtime already loaded the old
+ *  extension code. */
+export function getProviderExtensionSignature(
+  provider: string | undefined,
+  config: DelegateConfig = __delegateConfig,
+): string {
+  const sources = getSubagentProviderExtensionSourcesForProvider(
+    provider,
+    config,
+  );
+  if (sources.length === 0) return "";
+  // Preserve both ordering and provenance. Extension order may affect their
+  // initialization, and a user re-listing a shipped source changes it from
+  // best-effort to required. Treating either change as pool-compatible could
+  // reuse an extension-free session without performing the required checks.
+  // The signature crosses the session-pool boundary. Keep it opaque so a
+  // credential-bearing Git source can never become model-visible through a
+  // later pool mismatch. SHA-256 also keeps collision resistance appropriate
+  // for a key that decides whether already-loaded executable code may be reused.
+  return `sha256:${createHash("sha256")
+    .update(JSON.stringify(sources), "utf8")
+    .digest("hex")}`;
+}
+
 /** A provider-extension source together with how it entered the config. */
 export interface ProviderExtensionSource {
   /** The normalized source string, as the package manager consumes it. */
@@ -370,6 +845,46 @@ export function getSubagentProviderExtensionSourcesForProvider(
   }));
 }
 
+/** Get the effective per-agent overrides from delegate.json
+ *  (agent name → override), or undefined when unconfigured. */
+export function getAgentOverrides(
+  config: DelegateConfig = __delegateConfig,
+): Record<string, AgentOverride> | undefined {
+  return config.agentOverrides;
+}
+
+/** Get the parent-model-scoped overrides (`provider/model-id` → agent →
+ *  override), or undefined when unconfigured. */
+export function getAgentOverridesByParentModel(
+  config: DelegateConfig = __delegateConfig,
+): Record<string, Record<string, AgentOverride>> | undefined {
+  return config.agentOverridesByParentModel;
+}
+
+/** Re-read delegate.json from disk into the config singleton.
+ *
+ *  Called at the start of every tool execution so user edits to delegate.json
+ *  become visible between delegate calls without restarting pi. On parse or
+ *  read errors the existing snapshot is kept and a warning is emitted; a
+ *  deliberately deleted file falls back to defaults. */
+export function reloadDelegateConfig(): void {
+  const result = readDelegateConfigFromDisk();
+  if (result.status === "error") {
+    console.warn(
+      `[delegate] could not reload ${DELEGATE_CONFIG_SOURCE}; keeping current config: ${
+        result.error instanceof Error
+          ? result.error.message
+          : String(result.error)
+      }`,
+    );
+    return;
+  }
+  __delegateConfig =
+    result.status === "missing"
+      ? structuredClone(DEFAULT_DELEGATE_CONFIG)
+      : result.config;
+}
+
 // ── Config Getters ───────────────────────────────────────────────────────
 
 /**
@@ -385,23 +900,33 @@ export function getConcurrencyLimit(
 ): number {
   // 1. Per-model
   const perModel = config.concurrency.models?.[modelKey];
-  if (perModel != null) return perModel;
+  if (isPositiveInteger(perModel)) return perModel;
   // 2. Per-provider
-  const provider = modelKey.split("/")[0];
+  const provider = modelKey.split("/")[0] ?? modelKey;
   const perProvider = config.concurrency.providers?.[provider];
-  if (perProvider != null) return perProvider;
+  if (isPositiveInteger(perProvider)) return perProvider;
   // 3. Default
-  return config.concurrency.default;
+  return isPositiveInteger(config.concurrency.default)
+    ? config.concurrency.default
+    : MAX_CONCURRENCY;
 }
 
 /** Get the effective max async tickets limit. */
-export function getMaxAsyncTickets(): number {
-  return __delegateConfig.maxAsyncTickets ?? MAX_ASYNC_TICKETS;
+export function getMaxAsyncTickets(
+  config: DelegateConfig = __delegateConfig,
+): number {
+  return isPositiveInteger(config.maxAsyncTickets)
+    ? config.maxAsyncTickets
+    : MAX_ASYNC_TICKETS;
 }
 
 /** Get the hard ceiling on total concurrent agents. */
-export function getMaxConcurrent(): number {
-  return __delegateConfig.maxConcurrent ?? MAX_CONCURRENCY;
+export function getMaxConcurrent(
+  config: DelegateConfig = __delegateConfig,
+): number {
+  return isPositiveInteger(config.maxConcurrent)
+    ? config.maxConcurrent
+    : MAX_CONCURRENCY;
 }
 
 /** Maximum inactivity before cooperative stall cancellation is requested.
@@ -410,36 +935,45 @@ export function getStallTimeoutMs(
   config: DelegateConfig = __delegateConfig,
 ): number {
   const configured = stallTimeoutOverrideForTesting ?? config.stallTimeoutMs;
-  if (
-    typeof configured === "number" &&
-    Number.isFinite(configured) &&
-    configured >= 0
-  ) {
-    return configured;
-  }
-  return DEFAULT_DELEGATE_CONFIG.stallTimeoutMs!;
+  return isNonNegativeInteger(configured)
+    ? configured
+    : DEFAULT_DELEGATE_CONFIG.stallTimeoutMs!;
 }
 
 /** Get the max whole-task retries after the initial attempt. */
-export function getWholeTaskMaxRetries(): number {
-  return __delegateConfig.retry?.wholeTaskMaxRetries ?? 3;
+export function getWholeTaskMaxRetries(
+  config: DelegateConfig = __delegateConfig,
+): number {
+  return isNonNegativeInteger(config.retry?.wholeTaskMaxRetries)
+    ? config.retry!.wholeTaskMaxRetries
+    : 3;
 }
 
 /** Get the base delay (ms) for whole-task retry exponential backoff. */
-export function getWholeTaskBaseDelayMs(): number {
-  return __delegateConfig.retry?.wholeTaskBaseDelayMs ?? 1_000;
+export function getWholeTaskBaseDelayMs(
+  config: DelegateConfig = __delegateConfig,
+): number {
+  return isNonNegativeInteger(config.retry?.wholeTaskBaseDelayMs)
+    ? config.retry!.wholeTaskBaseDelayMs
+    : 1_000;
 }
 
 /** Get the output-spill threshold (chars). Over this, final output is spilled. */
-export function getOutputSpillThreshold(): number {
-  return (
-    __delegateConfig.output?.spillThresholdChars ?? OUTPUT_SPILL_THRESHOLD_CHARS
-  );
+export function getOutputSpillThreshold(
+  config: DelegateConfig = __delegateConfig,
+): number {
+  return isPositiveInteger(config.output?.spillThresholdChars)
+    ? config.output!.spillThresholdChars
+    : OUTPUT_SPILL_THRESHOLD_CHARS;
 }
 
 /** Get the output-spill tail length (chars) kept in-context when spilled. */
-export function getOutputSpillTail(): number {
-  return __delegateConfig.output?.spillTailChars ?? OUTPUT_SPILL_TAIL_CHARS;
+export function getOutputSpillTail(
+  config: DelegateConfig = __delegateConfig,
+): number {
+  return isNonNegativeInteger(config.output?.spillTailChars)
+    ? config.output!.spillTailChars
+    : OUTPUT_SPILL_TAIL_CHARS;
 }
 
 /**