@nredd/pi-subagents 0.22.0-nredd.7 → 0.22.0-nredd.8

package/src/nested-tools.ts

@@ -17,8 +17,7 @@ import {
 } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { isolationParam, resolveAgentInvocationConfig } from "./invocation-config.js";
-import { resolveModel } from "./model-resolver.js";
-import { checkModelScope } from "./model-scope.js";
+import { type ModelSelection, modelSelectionNote, selectModel } from "./model-selection.js";
 import {
   createOutputFilePath,
   getOutputTranscriptDefault,
@@ -75,8 +74,10 @@ export const NESTED_WORKFLOW_NO_AGENT_ERROR =
   + "Do the work directly.";
 
 interface NestedSpawnOptions {
+  homeDir?: string;
   description: string;
   model?: Model<any>;
+  modelSelection?: ModelSelection;
   maxTurns?: number;
   isolated?: boolean;
   inheritContext?: boolean;
@@ -120,6 +121,8 @@ export interface NestedAgentManager {
 }
 
 export interface NestedToolContext {
+  /** Home shared by this branch's user-resource discovery. */
+  homeDir?: string;
   manager: NestedAgentManager;
   pi: ExtensionAPI;
   parentAgentId: string;
@@ -160,6 +163,13 @@ function ownsRecord(record: AgentRecord | undefined, parentAgentId: string): rec
 type ResultPosition = "inline" | "fetched";
 
 function formatRecord(record: AgentRecord, position: ResultPosition): string {
+  // Read off the record, so a fetched or resumed child reports what ran, not
+  // what the current call would have configured.
+  const note = modelSelectionNote(record);
+  return note ? `${note}\n\n${formatOutcome(record, position)}` : formatOutcome(record, position);
+}
+
+function formatOutcome(record: AgentRecord, position: ResultPosition): string {
   if (record.status === "error") {
     return `Agent failed: ${record.error ?? "unknown error"}${partialOutputSuffix(record)}`;
   }
@@ -181,7 +191,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
   // Agents resolve from a registry built for THIS branch's config root (under
   // worktree isolation, the copy). Never via registerAgents — that is
   // process-global state shared with the main session and every other agent.
-  const loadRegistry = () => buildAgentRegistry(loadCustomAgents(context.configCwd, false, { projectTrusted: context.projectTrusted }));
+  const loadRegistry = () => buildAgentRegistry(loadCustomAgents(context.configCwd, false, { projectTrusted: context.projectTrusted, homeDir: context.homeDir }));
   const allowedTypesIn = (registry: Map<string, AgentConfig>): Set<string> | undefined =>
     context.allowedSubagents === "all"
       ? undefined
@@ -201,7 +211,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
       prompt: Type.String({ description: "Self-contained task for the nested agent." }),
       description: Type.String({ description: "Short 3-5 word task description." }),
       subagent_type: Type.String({ description: `Allowed nested agent type. Available: ${availableIn(loadRegistry()).join(", ") || "none"}.` }),
-      model: Type.Optional(Type.String({ description: "Optional provider/model override." })),
+      model: Type.Optional(Type.String({ description: "Optional configured @tier or provider/model override; explicit values win over agentModels and the definition." })),
       thinking: Type.Optional(Type.String({ description: "Optional thinking level." })),
       max_turns: Type.Optional(Type.Number({ minimum: 1 })),
       run_in_background: Type.Optional(
@@ -273,40 +283,26 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
       // Foreground regardless of `backgroundByDefault` — see the reasoning on
       // ResolveOptions. An explicit `true` here still opts in.
       const invocation = resolveAgentInvocationConfig(config, params, {
-        agentType: resolvedType,
         worktreeAllowed: isWorktreeIsolationEnabled(),
         defaultRunInBackground: false,
       });
-      let model = ctx.model;
-      if (invocation.modelInput) {
-        const resolvedModel = resolveModel(invocation.modelInput, ctx.modelRegistry);
-        if (typeof resolvedModel === "string") {
-          if (invocation.modelFromParams) return textResult(resolvedModel, true);
-        } else {
-          model = resolvedModel;
-        }
-      }
-
-      // Same scopeModels policy as the top-level Agent tool — a nested spawn
-      // must not escape the allowlist. A "warn" verdict proceeds silently:
-      // child sessions have no UI surface to toast to.
-      const scopeVerdict = checkModelScope({
-        model,
-        cwd: context.configCwd,
-        modelRegistry: ctx.modelRegistry,
-        callerSupplied: invocation.modelFromParams,
-        agentLabel: config?.displayName ?? resolvedType,
-        modelInput: invocation.modelInput,
+      const selection = selectModel({
+        homeDir: context.homeDir,
+        agentType: resolvedType, definitionModel: config?.model, paramModel: params.model,
+        parentModel: ctx.model, registry: ctx.modelRegistry, cwd: context.configCwd, agentLabel: config?.displayName,
       });
-      if (scopeVerdict.kind === "error") return textResult(scopeVerdict.message, true);
+      if (typeof selection === "string") return textResult(selection, true);
+      const model = selection.model;
 
       // The whole branch shares the root session's transcript directory; read it
       // off the owning parent rather than this child session's own id.
       const rootSessionId = context.manager.getRecord(context.parentAgentId)?.rootSessionId;
       const childDepth = context.depth + 1;
       const options: NestedSpawnOptions = {
+        homeDir: context.homeDir,
         description: params.description,
         model,
+        modelSelection: selection,
         maxTurns: invocation.maxTurns,
         isolated: invocation.isolated,
         inheritContext: invocation.inheritContext,

package/src/output-file.ts

@@ -5,10 +5,12 @@
  * matching Claude Code's task output file format.
  */
 
-import { appendFileSync, chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { type ModelFallback, modelFallbackNote } from "./model-resolver.js";
+import { type TierDisclosure, tierDisclosure, tierNote } from "./model-tiers.js";
 
 /**
  * Project/global default for writing a subagent's `.output` transcript; a custom
@@ -80,6 +82,26 @@ export function ensureOutputFile(path: string): void {
   } catch { /* ignore — streaming writes are best-effort too */ }
 }
 
+/** Append the model-fallback disclosure as a transcript line (best effort, like streaming writes). */
+export function appendModelFallbackEntry(path: string, agentId: string, fallback: ModelFallback): void {
+  try {
+    // A resumed agent reuses its transcript, which may already say it.
+    if (existsSync(path) && readFileSync(path, "utf-8").includes('"type":"model-fallback"')) return;
+    appendFileSync(
+      path,
+      `${JSON.stringify({ isSidechain: true, agentId, type: "model-fallback", modelFallback: fallback, note: modelFallbackNote(fallback), timestamp: new Date().toISOString() })}\n`,
+      "utf-8",
+    );
+  } catch { /* ignore */ }
+}
+
+/** Append tier provenance separately from assistant messages for durable replay. */
+export function appendModelTierEntry(path: string, agentId: string, modelTier: TierDisclosure): void {
+  try {
+    appendFileSync(path, `${JSON.stringify({ isSidechain: true, agentId, type: "model-tier", modelTier: tierDisclosure(modelTier), note: tierNote(modelTier), timestamp: new Date().toISOString() })}\n`, "utf-8");
+  } catch { /* transcript writes are best effort */ }
+}
+
 /** Write the initial user prompt entry. */
 export function writeInitialEntry(path: string, agentId: string, prompt: string, cwd: string): void {
   const entry = {

package/src/package-resources.ts

@@ -55,7 +55,8 @@
 
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { DefaultPackageManager, getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { normalizeHomePath, resolveAgentDir } from "./home-paths.js";
 
 /** Resource kinds a package may declare. Agents are `.md`, workflows are `.js`. */
 export type PackageResourceKind = "agents" | "workflows";
@@ -103,6 +104,8 @@ export interface PiPackage {
 export type PackageGate = boolean | string[] | undefined;
 
 export interface PackageDiscoveryOptions {
+  /** Home directory for user settings and installed resources, resolved at call time. */
+  homeDir?: string;
   /**
    * Pi's project-trust state for `cwd`, from `ctx.isProjectTrusted()`. When
    * false, `.pi/settings.json` is not read — so a package configured only by an
@@ -376,14 +379,26 @@ interface ConfiguredPackageRow {
  * so a later pi that drops or renames this API contributes no packages instead
  * of failing activation.
  */
-function configuredPackages(cwd: string, projectTrusted: boolean): ConfiguredPackageRow[] {
+function configuredPackages(cwd: string, projectTrusted: boolean, homeDir?: string): ConfiguredPackageRow[] {
   try {
     if (typeof DefaultPackageManager !== "function") return [];
-    const agentDir = getAgentDir();
+    const agentDir = resolveAgentDir(homeDir);
     const settingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted });
     const manager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
     if (typeof manager.listConfiguredPackages !== "function") return [];
-    return manager.listConfiguredPackages();
+    if (homeDir === undefined) return manager.listConfiguredPackages();
+    // Pi's enumerator expands local package sources through its own ambient
+    // home. Reuse its public installed-path resolver with normalized inputs,
+    // preserving the original source for package-gate matching and diagnostics.
+    const rows: ConfiguredPackageRow[] = [];
+    for (const scope of ["user", "project"] as const) {
+      const settings = scope === "user" ? settingsManager.getGlobalSettings() : settingsManager.getProjectSettings();
+      for (const pkg of settings.packages ?? []) {
+        const source = typeof pkg === "string" ? pkg : pkg.source;
+        rows.push({ source, scope, installedPath: manager.getInstalledPath(normalizeHomePath(source, homeDir), scope) });
+      }
+    }
+    return rows;
   } catch {
     return [];
   }
@@ -394,10 +409,10 @@ function configuredPackages(cwd: string, projectTrusted: boolean): ConfiguredPac
  * order (global entries first, then project). Duplicates by root are collapsed —
  * a package listed in both scopes is one package on disk.
  */
-export function listPiPackages(cwd: string, projectTrusted = false): PiPackage[] {
+export function listPiPackages(cwd: string, projectTrusted = false, homeDir?: string): PiPackage[] {
   const seen = new Set<string>();
   const out: PiPackage[] = [];
-  for (const entry of configuredPackages(cwd, projectTrusted)) {
+  for (const entry of configuredPackages(cwd, projectTrusted, homeDir)) {
     const root = entry.installedPath;
     if (!root || seen.has(root)) continue;
     const manifest = readPackageJson(root);
@@ -484,9 +499,9 @@ export function invalidatePackageCache(): void {
   cache.clear();
 }
 
-function scan(cwd: string, projectTrusted: boolean, gate: PackageGate): CacheEntry {
+function scan(cwd: string, projectTrusted: boolean, gate: PackageGate, homeDir?: string): CacheEntry {
   const entry = emptyEntry();
-  for (const pkg of listPiPackages(cwd, projectTrusted)) {
+  for (const pkg of listPiPackages(cwd, projectTrusted, homeDir)) {
     if (!packageAllowed(pkg, gate)) continue;
     // The root is normalized here, not at lookup time: the declared paths below
     // go through `resolve(root, entry)`, so a root that arrived with a trailing
@@ -520,10 +535,10 @@ function cacheEntryFor(cwd: string, kind: PackageResourceKind, opts: PackageDisc
   // `\u0000` written as an escape, not a raw byte: a literal NUL makes this
   // whole file read as binary to grep, ripgrep and git, which silently drops
   // it from search results.
-  const key = `${cwd}\u0000${projectTrusted ? 1 : 0}\u0000${JSON.stringify(gate ?? true)}`;
+  const key = `${cwd}\u0000${opts.homeDir ?? ""}\u0000${resolveAgentDir(opts.homeDir)}\u0000${projectTrusted ? 1 : 0}\u0000${JSON.stringify(gate ?? true)}`;
   let hit = cache.get(key);
   if (!hit) {
-    hit = scan(cwd, projectTrusted, gate);
+    hit = scan(cwd, projectTrusted, gate, opts.homeDir);
     cache.set(key, hit);
   }
   return hit;

package/src/process-budget.ts

@@ -247,10 +247,13 @@ function admits(s: BudgetState, depth: number): boolean {
   if (level > top) return false;
   // Leases deeper than `top` cannot exist while it is on; clamp so they still count in the total.
   const atDepth = new Array<number>(top + 1).fill(0);
-  for (const lease of s.active) atDepth[Math.min(top, Math.max(1, lease.depth))]++;
+  for (const lease of s.active) {
+    const index = Math.min(top, Math.max(1, lease.depth));
+    atDepth[index] = atDepth[index]! + 1;
+  }
   let atOrAbove = 0;
   for (let j = 1; j <= top; j++) {
-    atOrAbove += atDepth[j];
+    atOrAbove += atDepth[j]!;
     if (j >= level && atOrAbove >= admissionLimit(policy, j)) return false;
   }
   return true;
@@ -322,7 +325,7 @@ export function pumpBudget(): void {
       for (;;) {
         const i = s.waiters.findIndex(w => admits(s, w.depth) && w.ready());
         if (i === -1) break;
-        const [waiter] = s.waiters.splice(i, 1);
+        const waiter = s.waiters.splice(i, 1)[0]!;
         const lease = newLease(s, waiter.depth);
         try {
           waiter.grant(lease);

package/src/quota-admission.ts

@@ -4,7 +4,7 @@
  * Quota tracking lives in a separate extension (nredd/pi-subscription-router),
  * reached over `pi.events` with the same envelope as `cross-extension-rpc.ts`:
  * emit `router:rpc:admit` `{ requestId, model }`, reply on
- * `router:rpc:admit:reply:<requestId>` as `{ success, data?: { ok, resolvedModel?, resetAt?, wait? } }` (`resolvedModel` is ignored).
+ * `router:rpc:admit:reply:<requestId>` as `{ success, data?: { ok, resolvedModel?, resetAt?, wait? } }` (`resolvedModel` labels the admitted physical model).
  *
  * Admission fails open. No router installed, a slow router, a malformed reply
  * or a router error all admit the dispatch: quota is advisory here, and the
@@ -13,6 +13,7 @@
 
 import { nanoid } from "nanoid";
 import { type Clock, realClock } from "./clock.js";
+import type { TierAdmission } from "./model-tiers.js";
 
 export const ADMIT_CHANNEL = "router:rpc:admit";
 
@@ -50,34 +51,45 @@ export function modelRef(model: { provider: string; id: string }): string {
 }
 
 /** Resolve to the block when the router refuses `model`, else undefined. */
-export function checkAdmission(
+export async function checkAdmission(
   events: AdmissionEvents,
   model: string,
   timeoutMs = ADMIT_TIMEOUT_MS,
   clock: Clock = realClock,
 ): Promise<QuotaBlock | undefined> {
+  return (await admissionOutcome(events, model, timeoutMs, clock)).block;
+}
+
+/** Retain the physical admission label and whether the router supplied a signal. */
+export function admissionOutcome(
+  events: AdmissionEvents,
+  model: string,
+  timeoutMs = ADMIT_TIMEOUT_MS,
+  clock: Clock = realClock,
+): Promise<TierAdmission> {
   const requestId = nanoid();
   return new Promise(resolve => {
     let done = false;
-    const finish = (block: QuotaBlock | undefined) => {
+    const finish = (outcome: TierAdmission) => {
       if (done) return;
       done = true;
       timer.cancel();
       unsubscribe();
-      resolve(block);
+      resolve(outcome);
     };
     const unsubscribe = events.on(`${ADMIT_CHANNEL}:reply:${requestId}`, raw => {
-      const reply = raw as { success?: unknown; data?: { ok?: unknown; resetAt?: unknown; wait?: unknown } } | undefined;
-      if (reply?.success !== true || reply.data?.ok !== false) return finish(undefined);
+      const reply = raw as { success?: unknown; data?: { ok?: unknown; resolvedModel?: unknown; resetAt?: unknown; wait?: unknown } } | undefined;
+      if (reply?.success !== true || typeof reply.data?.ok !== "boolean") return finish({ quotaSignal: false });
+      if (reply.data.ok) return finish({ quotaSignal: true, resolvedModel: typeof reply.data.resolvedModel === "string" ? reply.data.resolvedModel : undefined });
       const resetAt = reply.data.resetAt;
       const wait = reply.data.wait;
-      finish({
+      finish({ quotaSignal: true, block: {
         model,
         resetAt: typeof resetAt === "number" && Number.isFinite(resetAt) ? resetAt : undefined,
         ...(typeof wait === "boolean" ? { wait } : {}),
-      });
+      } });
     });
-    const timer = clock.setTimeout(() => finish(undefined), timeoutMs);
+    const timer = clock.setTimeout(() => finish({ quotaSignal: false }), timeoutMs);
     events.emit(ADMIT_CHANNEL, { requestId, model });
   });
 }

package/src/resource-loader.ts

@@ -0,0 +1,51 @@
+/** Normalize explicit settings paths before Pi's real package manager resolves them. */
+import { DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { normalizeHomePath } from "./home-paths.js";
+
+type ResourceLoaderOptions = ConstructorParameters<typeof DefaultResourceLoader>[0];
+type ResourceSettings = ReturnType<SettingsManager["getGlobalSettings"]>;
+
+const RESOURCE_FIELDS = ["extensions", "skills", "prompts", "themes"] as const;
+
+/** Keep filter modifiers and non-home paths intact; only replace leading home references. */
+function expandSetting(entry: string, homeDir: string, modifiers = true): string {
+  const prefix = modifiers && /^[!+-]/.test(entry) ? entry[0] : "";
+  const path = entry.slice(prefix.length);
+  const trimmed = path.trim();
+  if (trimmed !== "~" && !trimmed.startsWith("~/") && !(process.platform === "win32" && trimmed.startsWith("~\\"))) return entry;
+  return prefix + normalizeHomePath(trimmed, homeDir);
+}
+
+/** Return copies so loading resources never changes persisted settings or their source objects. */
+export function normalizeResourceSettings(settings: ResourceSettings, homeDir: string): ResourceSettings {
+  const normalized = { ...settings };
+  for (const field of RESOURCE_FIELDS) {
+    if (settings[field]) normalized[field] = settings[field].map(entry => expandSetting(entry, homeDir));
+  }
+  if (settings.packages) {
+    normalized.packages = settings.packages.map(pkg => {
+      if (typeof pkg === "string") return expandSetting(pkg, homeDir, false);
+      const copy = { ...pkg, source: expandSetting(pkg.source, homeDir, false) };
+      for (const field of RESOURCE_FIELDS) {
+        if (pkg[field]) copy[field] = pkg[field].map(entry => expandSetting(entry, homeDir));
+      }
+      return copy;
+    });
+  }
+  return normalized;
+}
+
+/** Use the real loader/manager while preventing ambient-home expansion of explicit settings. */
+export function createHomeResourceLoader(options: ResourceLoaderOptions, homeDir?: string): DefaultResourceLoader {
+  if (homeDir === undefined) return new DefaultResourceLoader(options);
+  const settingsManager = options.settingsManager ?? SettingsManager.create(options.cwd, options.agentDir);
+  const globalSettings = settingsManager.getGlobalSettings.bind(settingsManager);
+  const projectSettings = settingsManager.getProjectSettings.bind(settingsManager);
+  // Wrap the public readers, not a cached snapshot: reload and project-trust
+  // decisions continue to be owned by Pi, and every read receives fresh copies.
+  Object.assign(settingsManager, {
+    getGlobalSettings: () => normalizeResourceSettings(globalSettings(), homeDir),
+    getProjectSettings: () => normalizeResourceSettings(projectSettings(), homeDir),
+  });
+  return new DefaultResourceLoader({ ...options, settingsManager });
+}

package/src/schedule.ts

@@ -15,15 +15,14 @@
  *     `subagent-notification` path. No new delivery code.
  */
 
-import type { Model } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Cron } from "croner";
 import { nanoid } from "nanoid";
 import type { AgentManager } from "./agent-manager.js";
 import { normalizeMaxTurns } from "./agent-runner.js";
-import { resolveSpawnType } from "./agent-types.js";
+import { getAgentConfig, resolveSpawnType } from "./agent-types.js";
 import { type Clock, realClock, type TimerHandle } from "./clock.js";
-import { resolveModel } from "./model-resolver.js";
+import { admitModelSelection, type ModelSelection, selectModel } from "./model-selection.js";
 import { checkAdmission, describeBlock, mayPark, modelRef, PARKED_RESUME_DELAY_MS, QUOTA_RESTART_GRACE_MS } from "./quota-admission.js";
 import type { ScheduleStore } from "./schedule-store.js";
 import type { IsolationMode, ScheduledSubagent, SubagentType, ThinkingLevel } from "./types.js";
@@ -54,6 +53,7 @@ export interface NewJobInput {
 
 /** Optional in-process scheduling dependencies; omitted clock uses native time. */
 export interface SubagentSchedulerOptions {
+  homeDir?: string;
   clock?: Clock;
 }
 
@@ -66,7 +66,7 @@ export class SubagentScheduler {
   private ctx: ExtensionContext | undefined;
   private manager: AgentManager | undefined;
 
-  constructor(options: SubagentSchedulerOptions = {}) {
+  constructor(private readonly options: SubagentSchedulerOptions = {}) {
     this.clock = options.clock ?? realClock;
   }
 
@@ -247,22 +247,34 @@ export class SubagentScheduler {
 
     store.update(id, { lastStatus: "running" });
 
-    // Resolve model at fire time — registry contents may have changed since the
-    // job was created (auth added/removed). Fall back silently to spawn-default
-    // if resolution fails; the spawn path handles undefined model gracefully.
-    let resolvedModel: Model<any> | undefined;
-    if (job.model) {
-      const r = resolveModel(job.model, ctx.modelRegistry);
-      if (typeof r !== "string") resolvedModel = r;
+    // Resolve the original request at fire time, using the same type and model
+    // policy as a manual dispatch. Never drop a failed explicit override.
+    const dispatch = resolveSpawnType(job.subagent_type);
+    const config = dispatch.ok ? getAgentConfig(dispatch.type) : undefined;
+    const selection = dispatch.ok ? selectModel({
+      homeDir: this.options.homeDir,
+      agentType: dispatch.type, definitionModel: config?.model, agentLabel: config?.displayName,
+      paramModel: job.model, parentModel: ctx.model, registry: ctx.modelRegistry, cwd: ctx.cwd,
+    }) : dispatch.message;
+    if (typeof selection === "string") {
+      store.update(id, { lastRun: new Date(this.clock.now()).toISOString(), lastStatus: "error" });
+      this.emit({ type: "error", jobId: id, error: selection });
+      return;
     }
 
+    if (selection.scopeWarning) ctx.ui.notify(selection.scopeWarning, "warning");
+
     // A quota-parked job re-asks the router before starting: the window it
     // waited for may have refilled while another is still exhausted.
-    const admissionModel = resolvedModel ?? ctx.model;
-    if (job.quotaParked && admissionModel) {
-      void checkAdmission(pi.events, modelRef(admissionModel)).then(block => {
+    const admissionModel = selection.model;
+    if ((job.quotaParked || selection.tierBinding) && admissionModel) {
+      const admission = selection.tierBinding
+        ? admitModelSelection(selection, ctx.modelRegistry, pi.events)
+        : checkAdmission(pi.events, modelRef(admissionModel));
+      void admission.then(block => {
+        if (this.store !== store || this.ctx !== ctx) return;
         if (!block) {
-          this.spawnJob(id, resolvedModel);
+          this.spawnJob(id, selection);
         } else if (mayPark(block) && block.resetAt > this.clock.now()) {
           this.repark(id, block.resetAt);
         } else {
@@ -272,10 +284,14 @@ export class SubagentScheduler {
           this.store?.update(id, { lastRun: new Date(this.clock.now()).toISOString(), lastStatus: "error" });
           this.emit({ type: "error", jobId: id, error: `${describeBlock(block)} The agent was not started.` });
         }
+      }).catch(error => {
+        if (this.store !== store) return;
+        store.update(id, { lastStatus: "error" });
+        this.emit({ type: "error", jobId: id, error: error instanceof Error ? error.message : String(error) });
       });
       return;
     }
-    this.spawnJob(id, resolvedModel);
+    this.spawnJob(id, selection);
   }
 
   /** Re-arm a quota-parked one-shot at a later reset instead of starting it. */
@@ -285,11 +301,12 @@ export class SubagentScheduler {
       enabled: true,
       schedule: new Date(resetAt + QUOTA_RESTART_GRACE_MS).toISOString(),
       lastStatus: undefined,
+      quotaParked: true,
     });
   }
 
   /** Spawn a fired job (bypassing the concurrency queue) and persist its outcome. */
-  private spawnJob(id: string, resolvedModel: Model<any> | undefined): void {
+  private spawnJob(id: string, selection: ModelSelection): void {
     const store = this.store;
     const pi = this.pi;
     const ctx = this.ctx;
@@ -312,7 +329,8 @@ export class SubagentScheduler {
         description: job.description,
         isBackground: true,
         bypassQueue: true,
-        model: resolvedModel,
+        model: selection.model,
+        modelSelection: selection,
         maxTurns: job.max_turns,
         isolated: job.isolated,
         thinkingLevel: job.thinking,

package/src/settings.ts

@@ -4,9 +4,10 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { NO_FALLBACK } from "./agent-types.js";
 import { readEnterpriseLocalManifest } from "./enterprise-local.js";
+import { resolveAgentDir } from "./home-paths.js";
+import { type ModelResolution, parseTierBinding, setModelTiers } from "./model-tiers.js";
 import { type BudgetPolicy, DEFAULT_BUDGET_POLICY } from "./process-budget.js";
 import type { AgentMentionMode, JoinMode, ViewerMarkdownMode, WidgetMode } from "./types.js";
 
@@ -268,6 +269,10 @@ export interface SubagentsSettings {
   fallbackSubagent?: string;
   /** Trusted-global logical name -> ordered canonical provider/model candidates. */
   modelAliases?: Record<string, string[]>;
+  /** Trusted global/enterprise exact model bindings; never read from a project. */
+  modelTiers?: Record<string, string[]>;
+  /** Missing/unavailable tier policy. Both default to inherit with disclosure. */
+  modelResolution?: ModelResolution;
   /**
    * Trusted-global map of agent `type` (or `"*"` for every type) -> model, in
    * any form `Agent({ model })` accepts. Precedence, highest first: the Agent
@@ -576,6 +581,24 @@ function sanitize(raw: unknown): SubagentsSettings {
   } else if (typeof r.fallbackSubagent === "string" && r.fallbackSubagent.trim()) {
     out.fallbackSubagent = r.fallbackSubagent.trim();
   }
+  if (r.modelTiers !== undefined) {
+    out.modelTiers = {};
+    if (r.modelTiers && typeof r.modelTiers === "object" && !Array.isArray(r.modelTiers)) {
+      for (const [tier, members] of Object.entries(r.modelTiers)) {
+        const binding = parseTierBinding(tier, members);
+        if (binding) out.modelTiers[tier] = binding.kind === "routed" ? [binding.profile] : binding.members;
+        else console.warn(`[pi-subagents] Ignoring invalid modelTiers entry "${tier}".`);
+      }
+    } else console.warn("[pi-subagents] Ignoring modelTiers: expected an object of tier -> model list.");
+  }
+  if (r.modelResolution && typeof r.modelResolution === "object" && !Array.isArray(r.modelResolution)) {
+    out.modelResolution = {};
+    for (const key of ["onUnmapped", "onUnavailable"] as const) {
+      const mode = (r.modelResolution as Record<string, unknown>)[key];
+      if (mode === "error" || mode === "inherit") out.modelResolution[key] = mode;
+      else if (mode !== undefined) console.warn(`[pi-subagents] Ignoring invalid modelResolution.${key}.`);
+    }
+  }
   if (r.modelAliases !== undefined) {
     const aliases = sanitizeModelAliases(r.modelAliases);
     if (aliases) out.modelAliases = aliases;
@@ -630,8 +653,8 @@ function sanitizeModelAliases(raw: unknown): Record<string, string[]> | undefine
   return aliases;
 }
 
-function globalPath(): string {
-  return join(getAgentDir(), "subagents.json");
+function globalPath(homeDir?: string): string {
+  return join(resolveAgentDir(homeDir), "subagents.json");
 }
 
 function projectPath(cwd: string): string {
@@ -655,16 +678,21 @@ function readSettingsFile(path: string): SubagentsSettings {
 }
 
 /** Load merged settings: global provides defaults, project overrides. */
-export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
+export function loadSettings(cwd: string = process.cwd(), homeDir?: string): SubagentsSettings {
   // Aliases pick the provider a subagent runs on, so they are machine
   // configuration: a cloned repo's project file must not redirect them.
   const {
     modelAliases: projectModelAliases,
+    modelTiers: projectModelTiers,
+    modelResolution: projectModelResolution,
     agentModels: projectAgentModels,
     maxActiveSubagents: projectMaxActive,
     nestedSubagentReserve: projectReserve,
     ...project
   } = readSettingsFile(projectPath(cwd));
+  if (projectModelTiers !== undefined || projectModelResolution !== undefined) {
+    console.warn("[pi-subagents] Ignoring modelTiers/modelResolution in project .pi/subagents.json: model policy is read from trusted global configuration only.");
+  }
   if (projectModelAliases !== undefined) {
     console.warn("[pi-subagents] Ignoring modelAliases in project .pi/subagents.json: aliases are read from trusted global configuration only.");
   }
@@ -676,14 +704,14 @@ export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
   if (projectMaxActive !== undefined || projectReserve !== undefined) {
     console.warn("[pi-subagents] Ignoring maxActiveSubagents/nestedSubagentReserve in project .pi/subagents.json: the process-wide budget is read from global configuration only.");
   }
-  return { ...trustedSettings(), ...project };
+  return { ...trustedSettings(homeDir), ...project };
 }
 
 /** Global settings with the enterprise manifest over them: the layer a project file cannot touch. */
-function trustedSettings(): SubagentsSettings {
-  const enterprise = readEnterpriseLocalManifest()?.subagents;
+function trustedSettings(homeDir?: string): SubagentsSettings {
+  const enterprise = readEnterpriseLocalManifest(homeDir)?.subagents;
   const enterpriseSettings = enterprise === undefined ? {} : sanitize(enterprise);
-  return { ...readSettingsFile(globalPath()), ...enterpriseSettings };
+  return { ...readSettingsFile(globalPath(homeDir)), ...enterpriseSettings };
 }
 
 /**
@@ -692,8 +720,8 @@ function trustedSettings(): SubagentsSettings {
  * how deep its own sessions nest, but not what the process-wide reserve
  * covers. A missing key means its default, so removing the cap turns it off.
  */
-export function loadBudgetPolicy(): BudgetPolicy {
-  const trusted = trustedSettings();
+export function loadBudgetPolicy(homeDir?: string): BudgetPolicy {
+  const trusted = trustedSettings(homeDir);
   return {
     maxActive: trusted.maxActiveSubagents ?? DEFAULT_BUDGET_POLICY.maxActive,
     nestedReserve: trusted.nestedSubagentReserve ?? DEFAULT_BUDGET_POLICY.nestedReserve,
@@ -728,6 +756,7 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   if (typeof s.maxSubagentDepth === "number") appliers.setMaxSubagentDepth(s.maxSubagentDepth);
   if (typeof s.fallbackSubagent === "string") appliers.setFallbackSubagent(s.fallbackSubagent);
   // Module state: reset when a session omits it, or the previous activation's aliases leak.
+  setModelTiers(s.modelTiers, s.modelResolution);
   appliers.setModelAliases(s.modelAliases);
   appliers.setAgentModels(s.agentModels);
   if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
@@ -775,10 +804,11 @@ export function applyAndEmitLoaded(
   appliers: SettingsAppliers,
   emit: SettingsEmit,
   cwd: string = process.cwd(),
+  homeDir?: string,
 ): SubagentsSettings {
-  const settings = loadSettings(cwd);
+  const settings = loadSettings(cwd, homeDir);
   applySettings(settings, appliers);
-  appliers.setBudgetPolicy(loadBudgetPolicy());
+  appliers.setBudgetPolicy(loadBudgetPolicy(homeDir));
   emit("subagents:settings_loaded", { settings });
   return settings;
 }