@ian-pascoe/pi-minimal-subagents 0.1.0 → 0.2.0

package/README.md

@@ -45,15 +45,15 @@ Project values override global values. Run `/reload` after editing either file.
 `minimalSubagents.modelRoles` gives the parent agent advisory names for
 eligible models. The extension defines no roles itself, performs no task
 classification, and does not route launches. The parent still passes the
-ordinary `model` argument and chooses `thinking_level` independently.
+ordinary `model` and `thinking_level` arguments separately.
 
 ```json
 {
   "minimalSubagents": {
     "modelRoles": {
-      "budget": "opencode-go/glm-5.2",
+      "budget": "opencode-go/glm-5.2:low",
       "design": {
-        "model": "opencode-go/kimi-k3",
+        "model": "opencode-go/kimi-k3:high",
         "hint": "UI design, visual critique, and frontend polish"
       }
     }
@@ -61,10 +61,18 @@ ordinary `model` argument and chooses `thinking_level` independently.
 }
 ```
 
+A recognized final suffix (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`,
+or `max`) is a preferred `thinking_level`, not part of the canonical model
+passed to `subagent`. Unsuffixed roles leave thinking selection independent.
 Role names and hints are trimmed, single-line text. Names may be up to 64
 characters and hints up to 500 characters. Models use canonical
 `provider/model` IDs and must be available under the effective `enabledModels`
-scope. Thinking-level suffixes such as `:xhigh` are invalid here.
+scope. The resolver matches the complete authored model ID first, so real
+colon-bearing IDs—including IDs ending in `:high`—remain exact model IDs;
+only an otherwise-unmatched recognized final suffix is treated as a thinking
+preference. A thinking level pinned in `enabledModels` neither supplies nor
+constrains a role preference, and normal spawn-time model-capability clamping
+still applies.
 
 Global and project roles merge by name in settings order. Expanded role
 objects merge by field; a project string replaces the whole global entry. A
@@ -122,8 +130,68 @@ children: `subagent`, `agent_message`, `subagent_wait`, `subagent_status`,
 only the three adjacent-coordination tools: `agent_message`, `subagent_wait`,
 and `subagent_status`.
 
-Deleting a child first uses the optional `trash` command when available and
-falls back to unlinking its session file. Each Child Agent has a persistent
-JSONL session. Append-only Root Agent Registry entries retain hierarchy and
-Delivery Evidence across reloads. Forking cancels and drains active work, then
-clones child session leaves so the fork receives an independent hierarchy.
+The `subagent` `tools` argument distinguishes capability presets from exact
+lists: `"read"` grants `read`, `grep`, `find`, and `ls`; `"modify"` adds
+`bash`, `edit`, and `write`; an array such as `["read"]` grants exactly the
+named ordinary tool and does not expand a preset. Coordinator tools are
+injected separately according to delegation and must not appear in `tools`;
+misuse returns an actionable error. Use the string preset when a child needs
+the complete read-only discovery bundle.
+
+`agent_message` reports whether a message was delivered through an active
+parent wait, queued for the recipient, or failed. `subagent_wait` can return an
+intermediate Wait Event containing a Coordination Message before the child turn
+settles; call it again for the terminal turn result. Pass optional `turn_id` to
+address an older retained turn exactly. Without it, waits select the oldest
+observable claimed or pending turn before the active/latest turn. A caller may
+have only one outstanding wait for the same source turn; a concurrent duplicate
+is rejected instead of competing for one Wait Event.
+
+The persisted Delivery Ledger records Coordination Messages, terminal results,
+globally increasing sequence, and wait ownership before delivery. Existing
+items retain their sequence; gaps from skipped malformed records are valid.
+Claims can name only active, latest, or retained turns. Once a wait returns an
+intermediate message, that wait path owns the rest of the source turn across
+reloads, forks, and newer turns. Automatic fallback retains its ordered queue
+reservation, treats idle notifications as advisory, and rechecks actual
+recipient idleness before injecting a message. Destination-session Delivery
+Evidence settles and compacts ledger items, preventing duplicate delivery and
+unbounded checkpoint growth. The pure Delivery Ledger state machine retains at
+most 20 pending wait-only terminal results per source agent; Coordination
+Messages are not removed by that terminal-retention limit. Delivered messages
+include stable delivery, source-agent, and source-turn identities in persisted
+details.
+
+Deleting a child first verifies its session header and persistent identity,
+then uses the optional `trash` command when available and falls back to
+unlinking its session file. Deletion prunes pending delivery state and retained
+recent-message projections sourced from the complete deleted subtree. Restore
+and clone perform the same ownership check and reopen the recorded child-session
+leaf.
+
+Registry replay and Delivery Evidence are scoped to the Root Agent's active
+session-tree branch. Registry writes use V2 records with complete field,
+identity, sequence, hierarchy, adjacency, destination, ordinary-tool ceiling,
+and coordinator-tool exclusion validation. Every available V2 agent has a
+selected leaf; only unavailable recovery placeholders may omit it. Valid V1
+records and checkpoints migrate during replay; invalid owned records are
+skipped with semantic diagnostic codes rather than disabling the extension.
+Persisted message activity carries an explicit `recorded_at` from the
+coordinator clock.
+
+`/tree` abandons old process-local work and restores the selected branch. Fork
+preparation is read-only; only confirmed fork shutdown interrupts work and
+clones the selected branch, so another extension can cancel a fork without
+freezing coordinator tools. Each clone records a new generation-specific
+identity/provenance pair, and the destination appends ownership for that clone's
+current session ID rather than reusing inherited ownership. If a
+process-local fork handoff is lost, recovery reads only the destination's
+selected branch and proceeds only when its canonical `parentSession` proves the
+source file; it never substitutes the source session's newer head.
+
+## Status and TUI
+
+Visible Child Agent rows show the canonical `provider/model:thinking` Runtime
+Profile. Status uses the live Runtime Profile while a runtime exists and falls
+back to the immutable Launch Contract otherwise. Live changes are observational:
+they do not rewrite persistence or change nested spawn defaults.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [
@@ -29,10 +29,6 @@
     "access": "public",
     "provenance": true
   },
-  "scripts": {
-    "test": "vitest run --config ../../vitest.config.ts --root .",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
-  },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
@@ -47,5 +43,9 @@
     "extensions": [
       "./src/index.ts"
     ]
+  },
+  "scripts": {
+    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   }
-}
+}

package/src/minimal-subagents-capabilities.ts

@@ -16,8 +16,6 @@ export const COORDINATOR_TOOL_NAMES = [
 
 const READ_TOOL_BUNDLE = ["read", "grep", "find", "ls"];
 const MODIFY_TOOL_BUNDLE = [...READ_TOOL_BUNDLE, "bash", "edit", "write"];
-const THINKING_SUFFIX_PATTERN = /:(?:off|minimal|low|medium|high|xhigh|max)$/;
-
 interface ModelReference {
   provider: string;
   id: string;
@@ -28,11 +26,6 @@ interface ScopedModelReference {
   thinkingLevel?: string;
 }
 
-/** Remove a recognized Pi thinking suffix without changing model IDs containing other colons. */
-export function stripThinkingSuffix(modelPattern: string): string {
-  return modelPattern.replace(THINKING_SUFFIX_PATTERN, "");
-}
-
 /** Build the authenticated runtime model enum from Pi's already-resolved model scope. */
 export function buildEligibleModelIds(input: {
   availableModels: readonly ModelReference[];
@@ -47,7 +40,7 @@ export function buildEligibleModelIds(input: {
   const result: string[] = [];
 
   for (const model of source) {
-    const canonicalId = stripThinkingSuffix(`${model.provider}/${model.id}`);
+    const canonicalId = `${model.provider}/${model.id}`;
     if (!seen.has(canonicalId)) {
       seen.add(canonicalId);
       result.push(canonicalId);
@@ -80,6 +73,13 @@ export function resolveOrdinaryToolSelection(
             ? MODIFY_TOOL_BUNDLE
             : selection;
   const uniqueRequested = [...new Set(requested)];
+  const coordinatorTools = new Set<string>(COORDINATOR_TOOL_NAMES);
+  const requestedCoordinatorTools = uniqueRequested.filter((name) => coordinatorTools.has(name));
+  if (requestedCoordinatorTools.length > 0) {
+    throw new Error(
+      `Minimal subagents ordinary tool selection: coordinator tools are injected separately and must not appear in tools: ${requestedCoordinatorTools.join(", ")}`,
+    );
+  }
   const available = new Set(context.availableTools);
   const ceiling = new Set(context.capabilityCeiling);
   const missing = uniqueRequested.filter((name) => !available.has(name));

package/src/minimal-subagents-config.ts

@@ -1,15 +1,41 @@
-import {
-  DEFAULT_MAX_SUBAGENT_DEPTH,
-  stripThinkingSuffix,
-} from "./minimal-subagents-capabilities.js";
+import type { JsonValue } from "@earendil-works/pi-ai";
+import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { Value } from "typebox/value";
+import { DEFAULT_MAX_SUBAGENT_DEPTH, THINKING_LEVELS } from "./minimal-subagents-capabilities.js";
 
 const MODEL_ROLE_NAME_MAX_LENGTH = 64;
 const MODEL_ROLE_HINT_MAX_LENGTH = 500;
 
+const JsonValueSchema = Type.Unsafe<JsonValue>({});
+const SettingsDocumentSchema = Type.Object({
+  minimalSubagents: Type.Optional(JsonValueSchema),
+});
+const MinimalSubagentsSettingsSchema = Type.Object({
+  maxSubagentDepth: Type.Optional(JsonValueSchema),
+  modelRoles: Type.Optional(JsonValueSchema),
+});
+const JsonObjectSchema = Type.Record(Type.String(), JsonValueSchema);
+const PositiveSafeIntegerSchema = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
+const MaxSubagentDepthSettingSchema = Type.Union([PositiveSafeIntegerSchema, Type.Null()]);
+const ShorthandModelRoleSchema = Type.String();
+const ExpandedModelRoleSchema = Type.Object(
+  {
+    model: Type.String(),
+    hint: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+);
+const ModelRoleEntriesSchema = Type.Record(Type.String(), JsonValueSchema);
+const ModelRolesSettingSchema = Type.Union([ModelRoleEntriesSchema, Type.Null()]);
+
+type ModelRoleThinkingLevel = (typeof THINKING_LEVELS)[number];
+
 /** Describes one user-authored advisory model role shown to subagent callers. */
 export interface MinimalSubagentsModelRole {
   name: string;
   model: string;
+  thinkingLevel?: ModelRoleThinkingLevel;
   hint?: string;
 }
 
@@ -20,75 +46,190 @@ export interface ResolvedMinimalSubagentsConfig {
   warnings: string[];
 }
 
+interface MinimalSubagentsSettingsDocument {
+  minimalSubagents?: JsonValue;
+}
+
 interface MinimalSubagentsConfigInput {
-  globalSettings: unknown;
-  projectSettings: unknown;
+  globalSettings: MinimalSubagentsSettingsDocument;
+  projectSettings: MinimalSubagentsSettingsDocument;
   eligibleModelIds: readonly string[];
 }
 
+type PiSettingsDocument = ReturnType<SettingsManager["getGlobalSettings"]>;
+type MinimalSubagentsSettingsDocumentInput = PiSettingsDocument | MinimalSubagentsSettingsDocument;
+
 interface MinimalSubagentsSettingsReader {
-  getGlobalSettings(): unknown;
-  getProjectSettings(): unknown;
+  getGlobalSettings(): MinimalSubagentsSettingsDocumentInput;
+  getProjectSettings(): MinimalSubagentsSettingsDocumentInput;
 }
 
 type SettingsScope = "global" | "project";
 
 interface ScopedSettingValue {
   scope: SettingsScope;
-  value: unknown;
+  value: ModelRoleWireValue;
+}
+
+interface ParsedMinimalSubagentsSettings {
+  maxSubagentDepth?: MaxSubagentDepthWireValue;
+  modelRoles?: ModelRolesWireValue;
+}
+
+type MaxSubagentDepthWireValue =
+  | { kind: "depth"; value: number }
+  | { kind: "reset" }
+  | { kind: "invalid" };
+
+type ModelRoleWireValue =
+  | { kind: "delete" }
+  | { kind: "shorthand"; model: string }
+  | { kind: "expanded"; fields: Static<typeof ExpandedModelRoleSchema> }
+  | { kind: "malformed-expanded"; fields: Record<string, JsonValue> }
+  | { kind: "invalid" };
+
+type ModelRolesWireValue =
+  | { kind: "reset" }
+  | { kind: "entries"; entries: ReadonlyMap<string, ModelRoleWireValue> }
+  | { kind: "invalid" };
+
+function parseMaxSubagentDepthWireValue(value: JsonValue): MaxSubagentDepthWireValue {
+  if (!Value.Check(MaxSubagentDepthSettingSchema, value)) return { kind: "invalid" };
+  return value === null ? { kind: "reset" } : { kind: "depth", value };
+}
+
+function parseModelRoleWireValue(value: JsonValue): ModelRoleWireValue {
+  if (value === null) return { kind: "delete" };
+  if (Value.Check(ShorthandModelRoleSchema, value)) return { kind: "shorthand", model: value };
+  if (Value.Check(JsonObjectSchema, value)) {
+    return Value.Check(ExpandedModelRoleSchema, value)
+      ? { kind: "expanded", fields: value }
+      : { kind: "malformed-expanded", fields: value };
+  }
+  return { kind: "invalid" };
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+function isExpandedModelRoleWireValue(
+  value: ModelRoleWireValue,
+): value is Extract<ModelRoleWireValue, { kind: "expanded" | "malformed-expanded" }> {
+  return value.kind === "expanded" || value.kind === "malformed-expanded";
+}
+
+function parseModelRolesWireValue(value: JsonValue): ModelRolesWireValue {
+  if (!Value.Check(ModelRolesSettingSchema, value)) return { kind: "invalid" };
+  if (value === null) return { kind: "reset" };
+  return {
+    kind: "entries",
+    entries: new Map(
+      Object.entries(value).map(([name, roleValue]) => [name, parseModelRoleWireValue(roleValue)]),
+    ),
+  };
+}
+
+function parsePiSettingsDocument(
+  settings: MinimalSubagentsSettingsDocumentInput,
+): MinimalSubagentsSettingsDocument {
+  if (!Value.Check(SettingsDocumentSchema, settings)) return {};
+  const parsed: MinimalSubagentsSettingsDocument = {};
+  if (settings.minimalSubagents !== undefined) {
+    parsed.minimalSubagents = settings.minimalSubagents;
+  }
+  return parsed;
 }
 
 function readMinimalSubagentsSettings(
-  settings: unknown,
+  settings: MinimalSubagentsSettingsDocument,
   scope: SettingsScope,
   warnings: string[],
-): Record<string, unknown> {
-  if (!isRecord(settings) || settings.minimalSubagents === undefined) return {};
-  if (isRecord(settings.minimalSubagents)) return settings.minimalSubagents;
+): ParsedMinimalSubagentsSettings {
+  if (!Value.Check(SettingsDocumentSchema, settings)) return {};
+  const minimalSubagents = settings.minimalSubagents;
+  if (minimalSubagents === undefined) return {};
+  if (Value.Check(MinimalSubagentsSettingsSchema, minimalSubagents)) {
+    const parsed: ParsedMinimalSubagentsSettings = {};
+    if (minimalSubagents.maxSubagentDepth !== undefined) {
+      parsed.maxSubagentDepth = parseMaxSubagentDepthWireValue(minimalSubagents.maxSubagentDepth);
+    }
+    if (minimalSubagents.modelRoles !== undefined) {
+      parsed.modelRoles = parseModelRolesWireValue(minimalSubagents.modelRoles);
+    }
+    return parsed;
+  }
   warnings.push(`${scope} minimalSubagents: expected an object`);
   return {};
 }
 
 function mergeModelRoleEntries(
-  globalValue: unknown,
-  projectValue: unknown,
+  globalValue: ModelRolesWireValue | undefined,
+  projectValue: ModelRolesWireValue | undefined,
   warnings: string[],
 ): Map<string, ScopedSettingValue> {
   const entries = new Map<string, ScopedSettingValue>();
-  if (globalValue !== undefined) {
-    if (isRecord(globalValue)) {
-      for (const [name, value] of Object.entries(globalValue)) {
-        entries.set(name, { scope: "global", value });
-      }
-    } else if (globalValue !== null) {
-      warnings.push("global minimalSubagents.modelRoles: expected an object or null");
+  if (globalValue?.kind === "entries") {
+    for (const [name, value] of globalValue.entries) {
+      entries.set(name, { scope: "global", value });
     }
+  } else if (globalValue?.kind === "invalid") {
+    warnings.push("global minimalSubagents.modelRoles: expected an object or null");
   }
-  if (projectValue === null) return new Map();
+  if (projectValue?.kind === "reset") return new Map();
   if (projectValue === undefined) return entries;
-  if (!isRecord(projectValue)) {
+  if (projectValue.kind === "invalid") {
     warnings.push("project minimalSubagents.modelRoles: expected an object or null");
     return entries;
   }
+  if (projectValue.kind !== "entries") return entries;
 
-  for (const [name, value] of Object.entries(projectValue)) {
-    if (value === null) {
+  for (const [name, value] of projectValue.entries) {
+    if (value.kind === "delete") {
       entries.delete(name);
       continue;
     }
     const inherited = entries.get(name)?.value;
-    entries.set(name, {
-      scope: "project",
-      value: isRecord(inherited) && isRecord(value) ? { ...inherited, ...value } : value,
-    });
+    const mergedValue =
+      inherited !== undefined &&
+      isExpandedModelRoleWireValue(inherited) &&
+      isExpandedModelRoleWireValue(value)
+        ? parseModelRoleWireValue({ ...inherited.fields, ...value.fields })
+        : value;
+    entries.set(name, { scope: "project", value: mergedValue });
   }
   return entries;
 }
 
+interface ResolvedModelRoleReference {
+  model: string;
+  thinkingLevel?: ModelRoleThinkingLevel;
+}
+
+function resolveThinkingLevelSuffix(suffix: string): ModelRoleThinkingLevel | undefined {
+  return THINKING_LEVELS.find((thinkingLevel) => thinkingLevel === suffix);
+}
+
+function resolveModelRoleReference(
+  model: string,
+  eligibleModels: ReadonlySet<string>,
+  path: string,
+  warnings: string[],
+): ResolvedModelRoleReference | undefined {
+  if (eligibleModels.has(model)) return { model };
+
+  const separatorIndex = model.lastIndexOf(":");
+  if (separatorIndex >= 0) {
+    const prefix = model.slice(0, separatorIndex);
+    const suffix = model.slice(separatorIndex + 1);
+    if (eligibleModels.has(prefix)) {
+      const thinkingLevel = resolveThinkingLevelSuffix(suffix);
+      if (thinkingLevel !== undefined) return { model: prefix, thinkingLevel };
+      warnings.push(`${path}: unknown thinking level suffix: ${suffix}`);
+      return undefined;
+    }
+  }
+
+  warnings.push(`${path}: model is not eligible: ${model}`);
+  return undefined;
+}
+
 function parseModelRoles(
   entries: ReadonlyMap<string, ScopedSettingValue>,
   eligibleModelIds: readonly string[],
@@ -109,70 +250,78 @@ function parseModelRoles(
     }
 
     const value = entry.value;
-    if (isRecord(value)) {
-      const unknownFields = Object.keys(value).filter((key) => key !== "model" && key !== "hint");
-      if (unknownFields.length > 0) {
-        warnings.push(`${path}: unknown field: ${unknownFields.join(", ")}`);
+    const expandedRoleObject = isExpandedModelRoleWireValue(value) ? value.fields : undefined;
+    if (expandedRoleObject !== undefined) {
+      const invalidFields = Object.keys(expandedRoleObject).filter(
+        (key) => key !== "model" && key !== "hint",
+      );
+      if (invalidFields.length > 0) {
+        warnings.push(`${path}: unknown field: ${invalidFields.join(", ")}`);
         continue;
       }
-    } else if (typeof value !== "string") {
+    } else if (value.kind !== "shorthand") {
       warnings.push(`${path}: expected a model string or expanded role object`);
       continue;
     }
 
-    const model = typeof value === "string" ? value : value.model;
-    if (typeof model !== "string" || model.length === 0 || model !== model.trim()) {
+    const modelValue =
+      expandedRoleObject === undefined && value.kind === "shorthand"
+        ? value.model
+        : expandedRoleObject?.model;
+    if (
+      !Value.Check(ShorthandModelRoleSchema, modelValue) ||
+      modelValue.length === 0 ||
+      modelValue !== modelValue.trim()
+    ) {
       warnings.push(`${path}: model must be a non-empty trimmed string`);
       continue;
     }
-    if (stripThinkingSuffix(model) !== model) {
-      warnings.push(
-        `${path}: thinking level suffixes are not allowed; choose thinking_level per spawn`,
-      );
-      continue;
-    }
-    if (!eligibleModels.has(model)) {
-      warnings.push(`${path}: model is not eligible: ${model}`);
-      continue;
-    }
+    const resolvedModel = resolveModelRoleReference(modelValue, eligibleModels, path, warnings);
+    if (resolvedModel === undefined) continue;
 
-    const hint = isRecord(value) ? value.hint : undefined;
+    const hintValue = expandedRoleObject?.hint;
     if (
-      hint !== undefined &&
-      (typeof hint !== "string" ||
-        hint.length === 0 ||
-        hint !== hint.trim() ||
-        /[\r\n]/.test(hint) ||
-        hint.length > MODEL_ROLE_HINT_MAX_LENGTH)
+      hintValue !== undefined &&
+      (!Value.Check(ShorthandModelRoleSchema, hintValue) ||
+        hintValue.length === 0 ||
+        hintValue !== hintValue.trim() ||
+        /[\r\n]/.test(hintValue) ||
+        hintValue.length > MODEL_ROLE_HINT_MAX_LENGTH)
     ) {
       warnings.push(`${path}.hint: expected trimmed single-line text up to 500 characters`);
       continue;
     }
-    roles.push({ name, model, ...(hint === undefined ? {} : { hint }) });
+    const role: MinimalSubagentsModelRole = {
+      name,
+      model: resolvedModel.model,
+    };
+    if (resolvedModel.thinkingLevel !== undefined) {
+      role.thinkingLevel = resolvedModel.thinkingLevel;
+    }
+    if (hintValue !== undefined && Value.Check(ShorthandModelRoleSchema, hintValue)) {
+      role.hint = hintValue;
+    }
+    roles.push(role);
   }
   return roles;
 }
 
 function resolveMaxSubagentDepth(
-  globalValue: unknown,
-  projectValue: unknown,
+  globalValue: MaxSubagentDepthWireValue | undefined,
+  projectValue: MaxSubagentDepthWireValue | undefined,
   warnings: string[],
 ): number {
   let resolvedDepth = DEFAULT_MAX_SUBAGENT_DEPTH;
-  if (globalValue !== undefined && globalValue !== null) {
-    if (Number.isSafeInteger(globalValue) && Number(globalValue) > 0) {
-      resolvedDepth = Number(globalValue);
-    } else {
-      warnings.push(
-        "global minimalSubagents.maxSubagentDepth: expected a positive safe integer or null",
-      );
-    }
+  if (globalValue?.kind === "depth") {
+    resolvedDepth = globalValue.value;
+  } else if (globalValue?.kind === "invalid") {
+    warnings.push(
+      "global minimalSubagents.maxSubagentDepth: expected a positive safe integer or null",
+    );
   }
   if (projectValue === undefined) return resolvedDepth;
-  if (projectValue === null) return DEFAULT_MAX_SUBAGENT_DEPTH;
-  if (Number.isSafeInteger(projectValue) && Number(projectValue) > 0) {
-    return Number(projectValue);
-  }
+  if (projectValue.kind === "reset") return DEFAULT_MAX_SUBAGENT_DEPTH;
+  if (projectValue.kind === "depth") return projectValue.value;
   warnings.push(
     "project minimalSubagents.maxSubagentDepth: expected a positive safe integer or null",
   );
@@ -210,8 +359,8 @@ export function resolveMinimalSubagentsSettings(
   eligibleModelIds: readonly string[],
 ): ResolvedMinimalSubagentsConfig {
   return resolveMinimalSubagentsConfig({
-    globalSettings: settings.getGlobalSettings(),
-    projectSettings: settings.getProjectSettings(),
+    globalSettings: parsePiSettingsDocument(settings.getGlobalSettings()),
+    projectSettings: parsePiSettingsDocument(settings.getProjectSettings()),
     eligibleModelIds,
   });
 }

package/src/minimal-subagents-context.ts

@@ -11,11 +11,17 @@ export function snapshotCommittedContext(
   return structuredClone(committed);
 }
 
+/** Carries the selected caller messages and whether child preparation should compact them. */
+export interface ImportedSubagentContext {
+  messages: AgentMessage[];
+  compact: boolean;
+}
+
 /** Select the imported message snapshot and defer expensive compact preparation to the child turn. */
 export function assembleImportedContext(
   mode: SessionContextMode,
   committedMessages: AgentMessage[],
-): { messages: AgentMessage[]; compact: boolean } {
+): ImportedSubagentContext {
   if (mode === "omit") return { messages: [], compact: false };
   return { messages: committedMessages, compact: mode === "compact" };
 }