@pi-unipi/subagents 2.6.1 → 2.9.0

package/src/budgets.ts

@@ -0,0 +1,285 @@
+/**
+ * @pi-unipi/subagents — Turn / tool / usage budgets
+ *
+ * Ported from pi-subagents src/runs/shared/{turn-budget,tool-budget,
+ * usage-budget}.ts. Semantics identical; env override uses OUR prefix
+ * (UNIPI_SUBAGENT_TOOL_BUDGET). In-process foreground children enforce the
+ * turn budget at assistant-turn boundaries and the tool budget by blocking
+ * tools past the hard cap.
+ */
+
+import type {
+  ResolvedTurnBudget,
+  ResolvedToolBudget,
+  ToolBudgetConfig,
+  TurnBudgetState,
+  ToolBudgetState,
+  UsageBudgetConfig,
+} from "./parity-types.js";
+
+// ============================================================================
+// Turn budget
+// ============================================================================
+
+export const DEFAULT_TURN_BUDGET_GRACE_TURNS = 1;
+
+export function resolveTurnBudgetConfig(
+  raw: unknown,
+  label = "turnBudget",
+): { turnBudget?: ResolvedTurnBudget; error?: string } {
+  if (raw === undefined) return {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { error: `${label} must be an object with maxTurns and optional graceTurns.` };
+  }
+  const unknownField = Object.keys(raw as Record<string, unknown>).find(
+    (key) => key !== "maxTurns" && key !== "graceTurns",
+  );
+  if (unknownField) return { error: `${label}.${unknownField} is not supported.` };
+  const budget = raw as { maxTurns?: unknown; graceTurns?: unknown };
+  if (typeof budget.maxTurns !== "number" || !Number.isInteger(budget.maxTurns) || budget.maxTurns < 1) {
+    return { error: `${label}.maxTurns must be an integer >= 1.` };
+  }
+  const graceTurns = budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS;
+  if (typeof graceTurns !== "number" || !Number.isInteger(graceTurns) || graceTurns < 0) {
+    return { error: `${label}.graceTurns must be an integer >= 0.` };
+  }
+  return { turnBudget: { maxTurns: budget.maxTurns, graceTurns } };
+}
+
+export function appendTurnBudgetSystemPrompt(
+  systemPrompt: string,
+  budget: { maxTurns: number; graceTurns?: number } | undefined,
+): string {
+  if (!budget) return systemPrompt;
+  const graceTurns = budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS;
+  const grace = graceTurns === 1 ? "1 additional assistant turn" : `${graceTurns} additional assistant turns`;
+  const block = [
+    "## Turn budget",
+    `This child run has a soft budget of ${budget.maxTurns} assistant turn${budget.maxTurns === 1 ? "" : "s"}.`,
+    `After that, ${grace} may be allowed only for a final wrap-up.`,
+    "When you approach or reach the soft budget, stop starting new tool work and return the final answer immediately.",
+    "If you continue past the soft budget plus grace turns, the supervisor may abort the run and return only partial output.",
+  ].join("\n");
+  return systemPrompt.trim() ? `${systemPrompt.trim()}\n\n${block}` : block;
+}
+
+export function turnBudgetSoftNote(budget: ResolvedTurnBudget, turnCount: number): string {
+  return `Turn budget wrap-up was requested after ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns}, grace ${budget.graceTurns}). Output may be partial.`;
+}
+
+export function turnBudgetExceededMessage(budget: ResolvedTurnBudget, turnCount: number): string {
+  return `Subagent exceeded turn budget after ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns} + grace ${budget.graceTurns}).`;
+}
+
+export function turnBudgetDeferredNote(budget: ResolvedTurnBudget, turnCount: number): string {
+  return `Turn-budget termination was deferred at ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns} + grace ${budget.graceTurns}) because the assistant started tool work. The run ended before another safe assistant boundary; output may be partial.`;
+}
+
+export function formatTurnBudgetOutput(message: string, output: string): string {
+  return output.trim()
+    ? `${message}\n\nPartial output before turn-budget abort:\n${output}`
+    : message;
+}
+
+export function turnBudgetDecision(
+  budget: ResolvedTurnBudget,
+  turnCount: number,
+  terminalAssistantStop: boolean,
+  toolWorkActiveOrStarting: boolean,
+  enforceHardLimit = false,
+): "continue" | "defer" | "abort" {
+  const hardLimit = budget.maxTurns + budget.graceTurns;
+  if (terminalAssistantStop || turnCount < hardLimit) return "continue";
+  if (toolWorkActiveOrStarting && !enforceHardLimit) return "defer";
+  return "abort";
+}
+
+export function turnBudgetState(
+  budget: ResolvedTurnBudget,
+  turnCount: number,
+  exceeded: boolean,
+): TurnBudgetState {
+  return {
+    ...budget,
+    turns: turnCount,
+    outcome: exceeded ? "exceeded" : "wrap-up-requested",
+  };
+}
+
+// ============================================================================
+// Tool budget
+// ============================================================================
+
+export const DEFAULT_TOOL_BUDGET_BLOCK = ["read", "grep", "find", "ls"] as const;
+export const TOOL_BUDGET_ENV = "UNIPI_SUBAGENT_TOOL_BUDGET";
+
+export function normalizeToolBudgetBlock(block: ToolBudgetConfig["block"] | undefined): "*" | string[] {
+  if (block === "*") return "*";
+  if (block === undefined) return [...DEFAULT_TOOL_BUDGET_BLOCK];
+  return [...new Set(block.map((tool) => tool.trim()).filter(Boolean))];
+}
+
+export function validateToolBudgetConfig(
+  raw: unknown,
+  label = "toolBudget",
+  options: { minimumHard?: 0 | 1 } = {},
+): { budget?: ResolvedToolBudget; error?: string } {
+  if (raw === undefined) return {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { error: `${label} must be an object with hard and optional soft/block.` };
+  }
+  const value = raw as ToolBudgetConfig;
+  const minimumHard = options.minimumHard ?? 1;
+  if (typeof value.hard !== "number" || !Number.isInteger(value.hard) || value.hard < minimumHard) {
+    return { error: `${label}.hard must be an integer >= ${minimumHard}.` };
+  }
+  if (value.soft !== undefined && (typeof value.soft !== "number" || !Number.isInteger(value.soft) || value.soft < 1)) {
+    return { error: `${label}.soft must be an integer >= 1 when provided.` };
+  }
+  if (value.soft !== undefined && value.soft > value.hard) {
+    return { error: `${label}.soft must be <= ${label}.hard.` };
+  }
+  if (value.block !== undefined && value.block !== "*") {
+    if (!Array.isArray(value.block)) return { error: `${label}.block must be "*" or an array of tool names.` };
+    if (value.block.length === 0) return { error: `${label}.block must contain at least one tool name.` };
+    for (const item of value.block) {
+      if (typeof item !== "string" || !item.trim()) return { error: `${label}.block must contain non-empty tool names.` };
+    }
+  }
+  return {
+    budget: {
+      hard: value.hard,
+      ...(value.soft !== undefined ? { soft: value.soft } : {}),
+      block: normalizeToolBudgetBlock(value.block),
+    },
+  };
+}
+
+export function shouldBlockToolForBudget(
+  budget: ResolvedToolBudget,
+  toolName: string,
+  nextToolCount: number,
+): boolean {
+  if (nextToolCount <= budget.hard) return false;
+  return budget.block === "*" || budget.block.includes(toolName);
+}
+
+export function toolBudgetSoftNudge(budget: ResolvedToolBudget, toolCount: number): string {
+  return `Tool budget soft limit reached after ${toolCount} tool call${toolCount === 1 ? "" : "s"} (soft ${budget.soft}, hard ${budget.hard}). Stop starting new browsing/search work and finalize from the context you already have.`;
+}
+
+export function toolBudgetBlockedMessage(budget: ResolvedToolBudget, toolName: string, toolCount: number): string {
+  return `Tool budget hard limit reached after ${toolCount} tool call${toolCount === 1 ? "" : "s"} (hard ${budget.hard}). The '${toolName}' tool is blocked so you can finalize from the context you already have.`;
+}
+
+export function toolBudgetState(
+  budget: ResolvedToolBudget,
+  toolCount: number,
+  blockedTool?: string,
+): ToolBudgetState {
+  const overHard = toolCount > budget.hard;
+  const overSoft = budget.soft !== undefined && toolCount >= budget.soft;
+  return {
+    ...budget,
+    toolCalls: toolCount,
+    outcome: overHard ? "hard-blocked" : overSoft ? "soft-reached" : "within-budget",
+  };
+}
+
+// ============================================================================
+// Usage budget
+// ============================================================================
+
+export interface UsageBudgetLimitConfig {
+  soft?: number;
+  hard: number;
+}
+
+export interface UsageBudgetState {
+  version: 1;
+  source: "reported";
+  tokens?: UsageBudgetLimitConfig & { used: number; outcome: "within-budget" | "soft-exceeded" | "hard-exceeded" };
+  costUsd?: UsageBudgetLimitConfig & { used: number; outcome: "within-budget" | "soft-exceeded" | "hard-exceeded" };
+  exhausted: boolean;
+  reason?: "tokens" | "costUsd";
+}
+
+function validateLimit(raw: unknown, label: string): { limit?: UsageBudgetLimitConfig; error?: string } {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { error: `${label} must be an object with hard and optional soft.` };
+  const value = raw as Record<string, unknown>;
+  const unknown = Object.keys(value).find((key) => key !== "soft" && key !== "hard");
+  if (unknown) return { error: `${label}.${unknown} is not supported.` };
+  if (typeof value.hard !== "number" || !Number.isFinite(value.hard) || value.hard <= 0) {
+    return { error: `${label}.hard must be a positive number.` };
+  }
+  if (value.soft !== undefined && (typeof value.soft !== "number" || !Number.isFinite(value.soft) || value.soft <= 0)) {
+    return { error: `${label}.soft must be a positive number when provided.` };
+  }
+  if (value.soft !== undefined && value.soft > value.hard) {
+    return { error: `${label}.soft must be <= ${label}.hard.` };
+  }
+  return { limit: { hard: value.hard, ...(value.soft !== undefined ? { soft: value.soft } : {}) } };
+}
+
+export function validateUsageBudgetConfig(value: unknown, label = "usageBudget"): { budget?: UsageBudgetConfig; error?: string } {
+  if (value === undefined) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) return { error: `${label} must be an object.` };
+  const raw = value as Record<string, unknown>;
+  const unknown = Object.keys(raw).find((key) => key !== "tokens" && key !== "costUsd");
+  if (unknown) return { error: `${label}.${unknown} is not supported.` };
+  const budget: UsageBudgetConfig = {};
+  if (raw.tokens !== undefined) {
+    const tokens = validateLimit(raw.tokens, `${label}.tokens`);
+    if (tokens.error) return { error: tokens.error };
+    if (tokens.limit) budget.tokens = tokens.limit;
+  }
+  if (raw.costUsd !== undefined) {
+    const costUsd = validateLimit(raw.costUsd, `${label}.costUsd`);
+    if (costUsd.error) return { error: costUsd.error };
+    if (costUsd.limit) budget.costUsd = costUsd.limit;
+  }
+  if (!budget.tokens && !budget.costUsd) return { error: `${label} must include tokens or costUsd.` };
+  return { budget };
+}
+
+function metricState(
+  limit: UsageBudgetLimitConfig | undefined,
+  used: number,
+): UsageBudgetState["tokens"] {
+  if (!limit) return undefined;
+  return {
+    ...limit,
+    used,
+    outcome: used >= limit.hard ? "hard-exceeded" : limit.soft !== undefined && used >= limit.soft ? "soft-exceeded" : "within-budget",
+  };
+}
+
+export function usageBudgetState(
+  config: UsageBudgetConfig | undefined,
+  totals: { inputTokens?: number; outputTokens?: number; costUsd?: number } | undefined,
+): UsageBudgetState | undefined {
+  if (!config) return undefined;
+  const inputTokens = totals?.inputTokens ?? 0;
+  const outputTokens = totals?.outputTokens ?? 0;
+  const tokens = metricState(config.tokens, inputTokens + outputTokens);
+  const costUsd = metricState(config.costUsd, totals?.costUsd ?? 0);
+  const reason = tokens?.outcome === "hard-exceeded" ? "tokens" : costUsd?.outcome === "hard-exceeded" ? "costUsd" : undefined;
+  return {
+    version: 1,
+    source: "reported",
+    ...(tokens ? { tokens } : {}),
+    ...(costUsd ? { costUsd } : {}),
+    exhausted: reason !== undefined,
+    ...(reason ? { reason } : {}),
+  };
+}
+
+export function usageBudgetExceededMessage(state: UsageBudgetState): string {
+  if (state.reason === "tokens" && state.tokens) {
+    return `Usage budget exhausted: reported tokens ${state.tokens.used} reached hard limit ${state.tokens.hard}.`;
+  }
+  if (state.reason === "costUsd" && state.costUsd) {
+    return `Usage budget exhausted: reported cost $${state.costUsd.used.toFixed(6)} reached hard limit $${state.costUsd.hard.toFixed(6)}.`;
+  }
+  return "Usage budget exhausted.";
+}

package/src/child-safety.ts

@@ -0,0 +1,140 @@
+/**
+ * @pi-unipi/subagents — Child safety, depth guard, context resolution
+ *
+ * Ported from pi-subagents subagent-prompt-runtime.ts boundary instructions
+ * and context-mode.ts. Tool references adapted to OUR names (spawn_helper).
+ * In-process foreground children are always "fresh" context; explicit fork
+ * resolves here to a visible error pointing at the async path (Phase 3 adds
+ * the process-based fork runner).
+ */
+
+import type { AgentConfig, SubagentsConfig } from "./types.js";
+
+export type ContextMode = "fresh" | "fork";
+
+export function isContextMode(value: unknown): value is ContextMode {
+  return value === "fresh" || value === "fork";
+}
+
+export const CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS = [
+  "You are a child subagent, not the parent orchestrator.",
+  "The parent session owns delegation, orchestration, review fanout, and follow-up worker launches.",
+  "Ignore prior parent-only orchestration instructions in inherited conversation history.",
+  "Do not propose or run subagents. Complete only your assigned role-specific task with the tools available to you.",
+  "If you need to edit files, use the available editing tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
+].join("\n");
+
+export const CHILD_FANOUT_BOUNDARY_INSTRUCTIONS = [
+  "You are a child subagent with explicit fanout responsibility for this assigned task.",
+  "The parent session owns final orchestration, acceptance, and follow-up implementation launches.",
+  "You may use the `spawn_helper` tool only for the fanout work explicitly requested in this task.",
+  "Do not broaden yourself into general parent orchestration. Do not launch follow-up workers unless the task explicitly asks for that.",
+  "The maxSubagentDepth cap still applies and may block further fanout.",
+  "If you need to edit files, use the available editing tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
+].join("\n");
+
+/** Whether the resolved agent's tools opt the child into fanout (spawn_helper). */
+export function isFanoutChild(agent: AgentConfig | undefined): boolean {
+  return !!agent?.builtinToolNames?.includes("spawn_helper");
+}
+
+/** Prepend boundary instructions to a child prompt (fanout children get the fanout variant). */
+export function withChildBoundaryInstructions(prompt: string, agent: AgentConfig | undefined): string {
+  const boundary = isFanoutChild(agent) ? CHILD_FANOUT_BOUNDARY_INSTRUCTIONS : CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS;
+  const text = prompt.trim();
+  return text ? `${boundary}\n\n${text}` : boundary;
+}
+
+// ============================================================================
+// Depth guard
+// ============================================================================
+
+export const MAX_SUBAGENT_DEPTH_ENV = "UNIPI_SUBAGENT_MAX_DEPTH";
+export const CURRENT_SUBAGENT_DEPTH_ENV = "UNIPI_SUBAGENT_DEPTH";
+
+/**
+ * Resolve the effective depth cap. An inherited stricter cap cannot be
+ * relaxed; per-agent caps can only tighten. Reference semantics.
+ */
+export function resolveMaxSubagentDepth(
+  agent: AgentConfig | undefined,
+  config: SubagentsConfig | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): number {
+  const inheritedRaw = env[MAX_SUBAGENT_DEPTH_ENV];
+  const inherited = inheritedRaw !== undefined && inheritedRaw.trim() !== "" ? Number(inheritedRaw) : undefined;
+  if (inherited !== undefined && Number.isInteger(inherited) && inherited >= 0) {
+    const agentCap = agent?.maxSubagentDepth;
+    if (agentCap !== undefined && Number.isInteger(agentCap) && agentCap >= 0 && agentCap < inherited) {
+      return agentCap;
+    }
+    return inherited;
+  }
+  const configured = config?.maxSubagentDepth;
+  if (configured !== undefined && Number.isInteger(configured) && configured > 0) return configured;
+  return 2; // reference default
+}
+
+/**
+ * Environment for a child process/session: depth counters increment so a
+ * child's own spawns hit the cap.
+ */
+export function childDepthEnv(env: NodeJS.ProcessEnv, maxDepth: number): Record<string, string> {
+  const currentRaw = env[CURRENT_SUBAGENT_DEPTH_ENV];
+  const current = currentRaw !== undefined && currentRaw.trim() !== "" ? Number(currentRaw) : 0;
+  return {
+    [MAX_SUBAGENT_DEPTH_ENV]: String(maxDepth),
+    [CURRENT_SUBAGENT_DEPTH_ENV]: String(Number.isInteger(current) && current >= 0 ? current + 1 : 1),
+  };
+}
+
+/** Whether spawning is blocked by the depth guard for this environment. */
+export function depthExceeded(env: NodeJS.ProcessEnv, maxDepth: number): boolean {
+  const currentRaw = env[CURRENT_SUBAGENT_DEPTH_ENV];
+  if (currentRaw === undefined || currentRaw.trim() === "") return false;
+  const current = Number(currentRaw);
+  return Number.isInteger(current) && current >= maxDepth;
+}
+
+// ============================================================================
+// Context resolution (in-process foreground)
+// ============================================================================
+
+export class ContextUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ContextUnavailableError";
+  }
+}
+
+/**
+ * Resolve launch context: explicit call value > config defaultSubagentContext >
+ * agent defaultContext > "fresh". Explicit fork on the IN-PROCESS path fails
+ * fast with a pointer to the async path (reference behavior: explicit fork
+ * never silently downgrades).
+ */
+export function resolveContext(
+  callContext: string | undefined,
+  agent: AgentConfig | undefined,
+  config: SubagentsConfig | undefined,
+): ContextMode {
+  if (callContext === "fresh" || callContext === "fork") return callContext;
+  if (callContext === "profile") {
+    return agent?.defaultContext ?? "fresh";
+  }
+  const configDefault = config?.defaultSubagentContext;
+  if (configDefault === "fresh" || configDefault === "fork") return configDefault;
+  return agent?.defaultContext ?? "fresh";
+}
+
+/**
+ * In-process foreground runs are always fresh-context. An explicit fork
+ * request rejects with guidance (Phase 3's process runner provides fork).
+ */
+export function assertForegroundContextSupported(mode: ContextMode, async: boolean): void {
+  if (mode === "fork" && !async) {
+    throw new ContextUnavailableError(
+      'context: "fork" requires background execution (run_in_background: true); the in-process foreground path is fresh-context only. Re-run with run_in_background, or use context: "fresh".',
+    );
+  }
+}

package/src/config.ts

@@ -0,0 +1,226 @@
+/**
+ * @pi-unipi/subagents — Config management
+ *
+ * Loads config from ~/.unipi/config/subagents.json (global)
+ * and <workspace>/.unipi/config/subagents.json (override).
+ * Auto-generates on first run. Repairs corrupted files.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { SubagentsConfig } from "./types.js";
+
+const DEFAULT_CONFIG: SubagentsConfig = {
+  maxConcurrent: 4,
+  enabled: true,
+  types: {
+    explore: { enabled: true },
+    work: { enabled: true },
+  },
+};
+
+/** Get global config path: ~/.unipi/config/subagents.json */
+function getGlobalConfigPath(): string {
+  return join(homedir(), ".unipi", "config", "subagents.json");
+}
+
+/** Get workspace config path: <cwd>/.unipi/config/subagents.json */
+function getWorkspaceConfigPath(cwd: string): string {
+  return join(cwd, ".unipi", "config", "subagents.json");
+}
+
+/** Ensure directory exists. */
+function ensureDir(filePath: string): void {
+  const dir = filePath.substring(0, filePath.lastIndexOf("/"));
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/** Ensure a directory exists (not a file path). */
+function ensureDirExists(dirPath: string): void {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/** Write config atomically (write then rename). */
+function writeConfigAtomic(filePath: string, config: SubagentsConfig): void {
+  const tmpPath = filePath + ".tmp";
+  writeFileSync(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+  renameSync(tmpPath, filePath);
+}
+
+/** Load and parse config from a path. Returns null on failure. */
+function loadConfigFromPath(filePath: string): SubagentsConfig | null {
+  if (!existsSync(filePath)) return null;
+
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(content);
+    // Basic validation
+    if (typeof parsed !== "object" || parsed === null) return null;
+    return parsed as SubagentsConfig;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate parity keys. Follows the reference behavior: invalid values for
+ * strict keys (toolTimeoutMs, budgets, concurrency caps) are rejected with a
+ * visible error rather than silently ignored. Best-effort keys (placement,
+ * logging mode) fall back to defaults like the reference does.
+ *
+ * Returns a list of validation problems; empty means valid.
+ */
+export function validateParityConfig(config: SubagentsConfig): string[] {
+  const problems: string[] = [];
+  const positiveInt = (label: string, value: unknown): void => {
+    if (value === undefined) return;
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0 || value > 2147483647) {
+      problems.push(`${label} must be a positive integer no greater than 2147483647 (got ${JSON.stringify(value)})`);
+    }
+  };
+
+  positiveInt("timeoutMs", config.timeoutMs);
+  positiveInt("toolTimeoutMs", config.toolTimeoutMs);
+  positiveInt("globalConcurrencyLimit", config.globalConcurrencyLimit);
+  if (config.maxSubagentSpawnsPerSession !== undefined && config.maxSubagentSpawnsPerSession !== 0) {
+    positiveInt("maxSubagentSpawnsPerSession", config.maxSubagentSpawnsPerSession);
+  }
+  if (config.maxSubagentSpawnsPerRun !== undefined && config.maxSubagentSpawnsPerRun !== 0) {
+    positiveInt("maxSubagentSpawnsPerRun", config.maxSubagentSpawnsPerRun);
+  }
+  if (config.maxActiveAsyncRunsPerSession !== undefined && config.maxActiveAsyncRunsPerSession !== 0) {
+    positiveInt("maxActiveAsyncRunsPerSession", config.maxActiveAsyncRunsPerSession);
+  }
+  if (config.maxSubagentDepth !== undefined) positiveInt("maxSubagentDepth", config.maxSubagentDepth);
+
+  if (config.defaultSubagentContext !== undefined && !['"fresh"', '"fork"'].includes(JSON.stringify(config.defaultSubagentContext))) {
+    problems.push(`defaultSubagentContext must be "fresh" or "fork" (got ${JSON.stringify(config.defaultSubagentContext)})`);
+  }
+  if (config.fleetViewPlacement !== undefined && !['"belowEditor"', '"aboveEditor"'].includes(JSON.stringify(config.fleetViewPlacement))) {
+    problems.push(`fleetViewPlacement must be "belowEditor" or "aboveEditor" (got ${JSON.stringify(config.fleetViewPlacement)}); falling back to "belowEditor"`);
+  }
+  if (
+    config.resultScanLogging !== undefined &&
+    !["all", "activity", "off"].includes(config.resultScanLogging)
+  ) {
+    problems.push(`resultScanLogging must be "all", "activity", or "off" (got ${JSON.stringify(config.resultScanLogging)})`);
+  }
+  if (config.inlineToolDisplay !== undefined && !["rich", "summary"].includes(config.inlineToolDisplay)) {
+    problems.push(`inlineToolDisplay must be "rich" or "summary" (got ${JSON.stringify(config.inlineToolDisplay)})`);
+  }
+  if (config.parallel) {
+    positiveInt("parallel.maxTasks", config.parallel.maxTasks);
+    positiveInt("parallel.concurrency", config.parallel.concurrency);
+  }
+  if (config.maxOutput) {
+    positiveInt("maxOutput.bytes", config.maxOutput.bytes);
+    positiveInt("maxOutput.lines", config.maxOutput.lines);
+  }
+
+  return problems;
+}
+
+/** Repair corrupted config: rename to .bak and generate fresh. */
+function repairCorrupted(filePath: string): SubagentsConfig {
+  const backupPath = filePath + ".bak";
+  try {
+    renameSync(filePath, backupPath);
+  } catch {
+    // If rename fails, just overwrite
+  }
+  writeConfigAtomic(filePath, DEFAULT_CONFIG);
+  return DEFAULT_CONFIG;
+}
+
+/**
+ * Initialize config on extension start.
+ * - If missing: generate with defaults
+ * - If corrupted: rename to .bak, generate fresh
+ * - If valid: load
+ */
+export function initConfig(cwd: string): SubagentsConfig {
+  const globalPath = getGlobalConfigPath();
+  const globalDir = join(homedir(), ".unipi", "config");
+  const globalAgentsDir = join(homedir(), ".unipi", "config", "agents");
+
+  // Ensure directories exist
+  ensureDirExists(globalDir);
+  ensureDirExists(globalAgentsDir);
+
+  // Load or create global config
+  let globalConfig = loadConfigFromPath(globalPath);
+  if (globalConfig === null) {
+    globalConfig = repairCorrupted(globalPath);
+  }
+
+  // Ensure workspace directories exist if workspace exists
+  const workspaceDir = join(cwd, ".unipi", "config");
+  const workspaceAgentsDir = join(cwd, ".unipi", "config", "agents");
+  if (cwd && !cwd.startsWith(homedir())) {
+    // Only create workspace dirs if not in home directory
+    ensureDirExists(workspaceDir);
+    ensureDirExists(workspaceAgentsDir);
+  }
+
+  // Load workspace override if exists
+  const workspacePath = getWorkspaceConfigPath(cwd);
+  const workspaceConfig = loadConfigFromPath(workspacePath);
+
+  if (workspaceConfig) {
+    // Merge: workspace overrides global on any field present
+    const merged: SubagentsConfig = {
+      ...globalConfig,
+      ...workspaceConfig,
+      types: {
+        ...globalConfig.types,
+        ...workspaceConfig.types,
+      },
+    };
+    reportConfigProblems(merged);
+    return merged;
+  }
+
+  reportConfigProblems(globalConfig);
+  return globalConfig;
+}
+
+/** Surface config validation problems visibly (non-fatal, reference behavior). */
+function reportConfigProblems(config: SubagentsConfig): void {
+  const problems = validateParityConfig(config);
+  for (const problem of problems) {
+    console.error(`[unipi/subagents] config: ${problem}`);
+  }
+}
+
+/** Load the RAW parsed global config (for parity settings extraction). */
+export function loadRawGlobalConfig(): Record<string, unknown> | null {
+  return loadConfigFromPath(getGlobalConfigPath()) as Record<string, unknown> | null;
+}
+
+/** Load the RAW parsed workspace config (for parity settings extraction). */
+export function loadRawWorkspaceConfig(cwd: string): Record<string, unknown> | null {
+  return loadConfigFromPath(getWorkspaceConfigPath(cwd)) as Record<string, unknown> | null;
+}
+
+/**
+ * Save global config.
+ */
+export function saveGlobalConfig(config: SubagentsConfig): void {
+  const globalPath = getGlobalConfigPath();
+  ensureDir(globalPath);
+  writeConfigAtomic(globalPath, config);
+}
+
+/**
+ * Save workspace config.
+ */
+export function saveWorkspaceConfig(cwd: string, config: SubagentsConfig): void {
+  const workspacePath = getWorkspaceConfigPath(cwd);
+  ensureDir(workspacePath);
+  writeConfigAtomic(workspacePath, config);
+}