@bacnh85/pi-subagent 0.15.3 → 0.16.1

package/extensions/roles-panel.ts

@@ -0,0 +1,182 @@
+/**
+ * `/subagent roles` panel (kernel lives in @bacnh85/pi-config-panel).
+ *
+ * Row model for role-based model routing: one string row per role (comma
+ * chain, blank = reset to default) and one string row per discovered agent
+ * (`subagent.agentModels` override, blank = inherit agent file settings).
+ * Saving writes both maps to the GLOBAL `~/.pi/agent/settings.json` under
+ * `subagent.roles` / `subagent.agentModels` (merge + atomic rename), then
+ * invalidates the agent cache.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { row } from "@bacnh85/pi-config-panel";
+import type { PanelGroup } from "@bacnh85/pi-config-panel";
+
+// ponytail: local structural type — the kernel only reads value/label/
+// description, so this stays compatible with the published 0.1.0 range while
+// completion support ships in 0.1.1 (no static import of new kernel symbols).
+interface CompletionItem {
+  value: string;
+  label?: string;
+  description?: string;
+}
+import type { AgentConfig } from "./agents.ts";
+import { DEFAULT_ROLES, readSubagentRoles, type RolesConfig } from "./roles.ts";
+
+// ---------------------------------------------------------------------------
+// Settings persistence (global only — repo .pi/settings.json is read-only)
+// ---------------------------------------------------------------------------
+
+function settingsPath(): string {
+  const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+  return join(agentDir, "settings.json");
+}
+
+/** Read the GLOBAL settings.json. Returns null only when the file is missing;
+ *  throws when the file exists but is not valid JSON (so a corrupt file can
+ *  never be silently overwritten by a panel save). */
+function readSettingsJson(): Record<string, unknown> | null {
+  const path = settingsPath();
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, "utf8");
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`settings.json root is not a JSON object (${path})`);
+    }
+    return parsed as Record<string, unknown>;
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("not a JSON object")) throw err;
+    throw new Error(`settings.json is not valid JSON (${path})`);
+  }
+}
+
+/** Read-modify-write the `subagent` section of the GLOBAL settings.json.
+ *  Writes a temp file then renames (atomic); never touches other keys.
+ *  Throws if the existing settings.json is corrupt (the file is left intact).
+ *  Returns false when nothing changes. */
+export function writeSubagentSection(patch: { roles?: RolesConfig["roles"]; agentModels?: RolesConfig["agentModels"] }): boolean {
+  const settings = readSettingsJson() ?? {};
+  const existing = (settings.subagent ?? {}) as Record<string, unknown>;
+  const subagent = { ...existing };
+  if (patch.roles !== undefined) subagent.roles = patch.roles;
+  if (patch.agentModels !== undefined) subagent.agentModels = patch.agentModels;
+  if (JSON.stringify(subagent) === JSON.stringify(existing)) return false;
+  const rolesEmpty = subagent.roles === undefined || (typeof subagent.roles === "object" && Object.keys(subagent.roles as object).length === 0);
+  const modelsEmpty = subagent.agentModels === undefined || (typeof subagent.agentModels === "object" && Object.keys(subagent.agentModels as object).length === 0);
+  if (rolesEmpty) delete subagent.roles;
+  if (modelsEmpty) delete subagent.agentModels;
+  // Preserve any unrelated subagent.* keys (forward compat); drop the section
+  // only when roles/agentModels were the only content.
+  if (Object.keys(subagent).length === 0) delete settings.subagent;
+  else settings.subagent = subagent;
+  const target = settingsPath();
+  mkdirSync(dirname(target), { recursive: true });
+  const tmp = `${target}.tmp-${Date.now()}`;
+  writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+  renameSync(tmp, target);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Row model — unit-testable without a TUI
+// ---------------------------------------------------------------------------
+
+export interface RolesPanelCfg {
+  /** Working copy: role name → comma chain ("" = use default). */
+  roles: Record<string, string>;
+  /** Working copy: agent name → override selector ("" = inherit). */
+  agentModels: Record<string, string>;
+}
+
+/** Completion sources for the panel's model rows (lazy — resolved per keypress). */
+export interface RolesPanelOptions {
+  /** Available model refs (`provider/id`), sorted; may be empty before registry sync. */
+  models: () => string[];
+  /** Known role names (defaults + configured), offered as `@role` on agent rows. */
+  roles: () => string[];
+}
+
+/** Seed a working config from current effective settings + bundled agents. */
+export function buildRolesPanelCfg(agents: AgentConfig[], current: RolesConfig): RolesPanelCfg {
+  const roleNames = new Set([...Object.keys(DEFAULT_ROLES), ...Object.keys(current.roles)]);
+  const cfg: RolesPanelCfg = { roles: {}, agentModels: {} };
+  for (const name of roleNames) {
+    // Only show explicitly-configured values; defaults render blank (= default).
+    const explicit = (current.roles[name] !== undefined && JSON.stringify(current.roles[name]) !== JSON.stringify(DEFAULT_ROLES[name]))
+      ? (Array.isArray(current.roles[name]) ? current.roles[name].join(", ") : String(current.roles[name]))
+      : "";
+    cfg.roles[name] = explicit;
+  }
+  for (const agent of agents) cfg.agentModels[agent.name] = current.agentModels[agent.name] ?? "";
+  return cfg;
+}
+
+/** Build panel groups. Role rows first, then one override row per agent.
+ *  `options` adds inline model/@role completions when provided (optional so
+ *  existing unit tests and non-TUI callers stay unchanged). */
+export function buildRows(cfg: RolesPanelCfg, agents: AgentConfig[], options?: RolesPanelOptions): PanelGroup[] {
+  const defaultChain = (name: string) => Array.isArray(DEFAULT_ROLES[name]) ? (DEFAULT_ROLES[name] as string[]).join(", ") : String(DEFAULT_ROLES[name] ?? "");
+  const modelItems = (): CompletionItem[] =>
+    (options?.models() ?? []).sort().map((ref) => ({ value: ref }));
+  const roleItems = (): CompletionItem[] =>
+    (options?.roles() ?? []).map((name) => ({ value: `@${name}`, description: "role chain" }));
+  // ponytail: opts spread keeps this compilable against kernel 0.1.0 (whose
+  // row() opts type lacks `completions`); the runtime contract is additive and
+  // 0.1.1+ consumes the field. Drop the cast when the dep floor moves to 0.1.1.
+  const withCompletions = (completions: () => CompletionItem[]) =>
+    ({ completions }) as unknown as { mask?: boolean };
+  const roleRows = Object.keys(cfg.roles).sort().map((name) => {
+    // Label shows the default chain so blank is meaningful.
+    return row(`role.${name}`, `@${name}  (default: ${defaultChain(name) || "none"})`, "string", cfg.roles[name], (v) => {
+      cfg.roles[name] = String(v ?? "").trim();
+    }, withCompletions(modelItems));
+  });
+  const agentRows = agents.map((agent) =>
+    row(`agent.${agent.name}`, agent.name, "string", cfg.agentModels[agent.name] ?? "", (v) => {
+      const value = String(v ?? "").trim();
+      if (value) cfg.agentModels[agent.name] = value;
+      else delete cfg.agentModels[agent.name];
+    }, withCompletions(() => [...modelItems(), ...roleItems()])),
+  );
+  return [
+    { key: "roles", label: "Model roles (chain, blank = default)", rows: roleRows },
+    { key: "agents", label: "Per-agent overrides (blank = inherit)", rows: agentRows },
+  ];
+}
+
+/** Convert a working config back to a settings patch. Blank values drop keys
+ *  (role falls back to default; agent override is removed). */
+export function cfgToPatch(cfg: RolesPanelCfg): { roles: RolesConfig["roles"]; agentModels: RolesConfig["agentModels"] } {
+  const roles: RolesConfig["roles"] = {};
+  for (const [name, chain] of Object.entries(cfg.roles)) {
+    const trimmed = chain.trim();
+    if (!trimmed) continue;
+    roles[name] = trimmed.includes(",") ? trimmed.split(",").map((s) => s.trim()).filter(Boolean) : trimmed;
+  }
+  const agentModels: RolesConfig["agentModels"] = {};
+  for (const [name, value] of Object.entries(cfg.agentModels)) {
+    const trimmed = value.trim();
+    if (trimmed) agentModels[name] = trimmed;
+  }
+  return { roles, agentModels };
+}
+
+/** Keep overrides for agents NOT shown in the panel (e.g. overrides for
+ *  project-local agents saved globally from another project) so a panel save
+ *  doesn't wipe them. Discovered-agent entries always follow the panel. */
+export function preserveUnknownAgentModels(
+  patch: RolesConfig["agentModels"],
+  discoveredNames: readonly string[],
+  existing: RolesConfig["agentModels"] | undefined,
+): RolesConfig["agentModels"] {
+  if (!existing) return patch;
+  const out = { ...patch };
+  for (const [name, value] of Object.entries(existing)) {
+    if (!discoveredNames.includes(name) && out[name] === undefined) out[name] = value;
+  }
+  return out;
+}

package/extensions/roles.ts

@@ -0,0 +1,263 @@
+/**
+ * Role-based model routing for pi-subagent.
+ *
+ * A role maps a *function* (fast / coder / smart / custom) to an ordered model
+ * chain in settings.json under `subagent.roles`. Agent frontmatter references
+ * roles via `@role` aliases (`model: @fast`), so remapping a function is one
+ * settings edit instead of N agent-file edits.
+ *
+ * Settings shape (`~/.pi/agent/settings.json`; repo `.pi/settings.json` is a
+ * read-only overlay honored when the project is trusted):
+ *
+ * {
+ *   "subagent": {
+ *     "roles": {
+ *       "fast": "nvidia/openai/gpt-oss-20b, opencode-go/deepseek-v4-flash",
+ *       "coder": ["zai-coding-cn/glm-5.1", "opencode-go/deepseek-v4-flash"],
+ *       "smart": "*"
+ *     },
+ *     "agentModels": { "reviewer": "@smart:high" }
+ *   }
+ * }
+ *
+ * - Role value: string (comma chain) or array. `*` / `@default` = parent model.
+ * - `@role` entries may reference other roles (visited-set cycle guard).
+ * - Unknown roles are skipped and recorded in `unresolved` for diagnostics.
+ * - A trailing `:thinking` suffix (off|minimal|low|medium|high|xhigh|max) on
+ *   any entry overrides the agent's frontmatter thinking for that match.
+ *   Strict trailing match only — openrouter ids like `model:free` keep intact.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentConfig } from "./agents.ts";
+
+export type SubagentThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+const THINKING_LEVELS: readonly string[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+
+/** Role → raw chain value (string/array, may contain `@role` and `*` refs). */
+export type RoleMap = Record<string, string | string[]>;
+
+export interface RolesConfig {
+  roles: RoleMap;
+  /** Per-agent model override (agent name → selector / role alias / `*`). */
+  agentModels: Record<string, string>;
+}
+
+export interface ExpandedCandidates {
+  /** Concrete candidate names in priority order (may be empty = parent fallback). */
+  candidates: string[];
+  /** thinking suffix per matched candidate name (name as written, without suffix). */
+  thinkingByCandidate: Map<string, SubagentThinkingLevel>;
+  /** Unknown role aliases encountered (for diagnostics). */
+  unresolved: string[];
+}
+
+/** Today's bundled chains, as role defaults — behavior-preserving baseline. */
+export const DEFAULT_ROLES: RoleMap = {
+  fast: ["zai-coding-cn/glm-5-turbo", "nvidia/openai/gpt-oss-20b", "opencode-go/deepseek-v4-flash"],
+  coder: [
+    "zai-coding-cn/glm-5.1",
+    "nvidia/mistralai/mistral-small-4-119b-2603",
+    "openrouter/nvidia/nemotron-3-super-120b-a12b:free",
+    "opencode-go/deepseek-v4-flash",
+  ],
+  smart: ["zai-coding-cn/glm-5.3", "openrouter/nvidia/nemotron-3-ultra-550b-a55b:free", "opencode-go/deepseek-v4-pro"],
+};
+
+// ---------------------------------------------------------------------------
+// Settings reading
+// ---------------------------------------------------------------------------
+
+function agentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+}
+
+function readJson(path: string): Record<string, unknown> | null {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function subagentSection(json: Record<string, unknown> | null): Record<string, unknown> {
+  const section = json?.subagent;
+  return section && typeof section === "object" && !Array.isArray(section)
+    ? (section as Record<string, unknown>)
+    : {};
+}
+
+/** Normalize a role value: comma string → array of trimmed non-empty entries. */
+function normalizeChain(value: string | string[]): string[] {
+  const entries = typeof value === "string" ? value.split(",") : value;
+  return entries
+    .map((entry) => String(entry).trim())
+    .filter(Boolean);
+}
+
+/** Merge `subagent.roles` / `subagent.agentModels` from a settings JSON into cfg. */
+function mergeSection(cfg: RolesConfig, json: Record<string, unknown> | null): void {
+  const section = subagentSection(json);
+  const roles = section.roles;
+  if (roles && typeof roles === "object" && !Array.isArray(roles)) {
+    for (const [name, value] of Object.entries(roles as RoleMap)) {
+      if (value === null || value === undefined) continue;
+      const chain = normalizeChain(value as string | string[]);
+      if (chain.length > 0) cfg.roles[name] = chain;
+    }
+  }
+  const agentModels = section.agentModels;
+  if (agentModels && typeof agentModels === "object" && !Array.isArray(agentModels)) {
+    for (const [name, value] of Object.entries(agentModels as Record<string, unknown>)) {
+      if (typeof value === "string" && value.trim()) cfg.agentModels[name] = value.trim();
+    }
+  }
+}
+
+/**
+ * Read effective roles config. Precedence: global settings.json → repo
+ * `.pi/settings.json` (project-trusted only) → `(ctx as any).settings` (the
+ * SDK-layered view, when present). Later layers win per role/agent key.
+ */
+export function readSubagentRoles(ctx?: ExtensionContext): RolesConfig {
+  const cfg: RolesConfig = {
+    roles: structuredClone(DEFAULT_ROLES),
+    agentModels: {},
+  };
+  mergeSection(cfg, readJson(join(agentDir(), "settings.json")));
+  try {
+    if (ctx?.isProjectTrusted?.()) {
+      mergeSection(cfg, readJson(join(ctx.cwd, ".pi", "settings.json")));
+    }
+  } catch { /* untrusted or ctx without cwd — global only */ }
+  const layered = (ctx as unknown as { settings?: Record<string, unknown> } | undefined)?.settings;
+  if (layered) mergeSection(cfg, layered);
+  return cfg;
+}
+
+/** Global-only variant used by the panel so a save never persists repo
+ *  `.pi/settings.json` overlay values into the user's global settings. */
+export function readSubagentRolesGlobal(): RolesConfig {
+  const cfg: RolesConfig = {
+    roles: structuredClone(DEFAULT_ROLES),
+    agentModels: {},
+  };
+  mergeSection(cfg, readJson(join(agentDir(), "settings.json")));
+  return cfg;
+}
+
+// ---------------------------------------------------------------------------
+// Expansion
+// ---------------------------------------------------------------------------
+
+/** Split a trailing `:thinking` suffix. Returns null when the trailing segment
+ *  is not a known level (e.g. openrouter `:free`), leaving the name intact. */
+export function splitThinkingSuffix(name: string): { name: string; thinking?: SubagentThinkingLevel } {
+  const idx = name.lastIndexOf(":");
+  if (idx <= 0 || idx >= name.length - 1) return { name };
+  const suffix = name.slice(idx + 1);
+  if (!THINKING_LEVELS.includes(suffix)) return { name };
+  return { name: name.slice(0, idx), thinking: suffix as SubagentThinkingLevel };
+}
+
+function isParentRef(entry: string): boolean {
+  return entry === "*" || entry === "@default";
+}
+
+/**
+ * Expand a raw candidate list into concrete model names.
+ * `@role` entries expand in place (recursively, cycle-safe); `*` / `@default`
+ * resolve to an empty list (= parent fallback in resolveModel).
+ */
+export function expandModelCandidates(candidates: readonly string[], roles: RoleMap): ExpandedCandidates {
+  const out: string[] = [];
+  const thinkingByCandidate = new Map<string, SubagentThinkingLevel>();
+  const unresolved: string[] = [];
+  const seen = new Set<string>();
+
+  const pushEntry = (entry: string, thinking?: SubagentThinkingLevel): void => {
+    const { name, thinking: own } = splitThinkingSuffix(entry);
+    if (!name) return;
+    if (isParentRef(name)) return; // parent fallback: resolveModel handles the tail
+    if (seen.has(name)) {
+      // Earlier occurrence wins for thinking too (priority order).
+      return;
+    }
+    seen.add(name);
+    out.push(name);
+    const level = own ?? thinking;
+    if (level) thinkingByCandidate.set(name, level);
+  };
+
+  const walk = (entry: string, visited: Set<string>, inheritedThinking?: SubagentThinkingLevel): void => {
+    const raw = entry.trim();
+    if (!raw) return;
+    const { name: bare, thinking: own } = splitThinkingSuffix(raw);
+    if (isParentRef(bare)) return;
+    if (bare.startsWith("@")) {
+      const roleName = bare.slice(1);
+      const value = roles[roleName];
+      if (value === undefined || normalizeChain(value).length === 0) {
+        if (!unresolved.includes(bare)) unresolved.push(bare);
+        return;
+      }
+      if (visited.has(roleName)) return; // cycle guard
+      const next = new Set(visited).add(roleName);
+      // A suffix on the role reference ("@smart:high") applies to every model
+      // the role expands to; per-entry suffixes win over the inherited one.
+      const effective = own ?? inheritedThinking;
+      for (const child of normalizeChain(value)) walk(child, next, effective);
+      return;
+    }
+    pushEntry(bare, own ?? inheritedThinking);
+  };
+
+  for (const entry of candidates) walk(entry, new Set());
+  return { candidates: out, thinkingByCandidate, unresolved };
+}
+
+export interface AgentModelChain {
+  candidates: string[];
+  thinkingByCandidate: Map<string, SubagentThinkingLevel>;
+  unresolved: string[];
+  /** True when `subagent.agentModels` replaced the agent's own list. */
+  overridden: boolean;
+}
+
+/**
+ * Effective model chain for an agent: `subagent.agentModels[name]` (if set)
+ * replaces the agent's own candidates entirely, then `@role` / `:thinking`
+ * entries expand. No settings → bundled defaults → today's exact chains.
+ */
+export function resolveAgentModelChain(
+  agent: Pick<AgentConfig, "name" | "model" | "models">,
+  roles: RolesConfig,
+): AgentModelChain {
+  const override = roles.agentModels[agent.name];
+  const raw =
+    override !== undefined
+      ? [override]
+      : [...new Set([agent.model, ...(agent.models ?? [])].filter((model): model is string => Boolean(model)))];
+  const expanded = expandModelCandidates(raw, roles.roles);
+  return { ...expanded, overridden: override !== undefined };
+}
+
+/** Human-readable effective chain for prompt catalog + `/subagent` details. */
+export function describeAgentModels(
+  agent: Pick<AgentConfig, "name" | "model" | "models">,
+  roles: RolesConfig,
+): string {
+  const raw =
+    roles.agentModels[agent.name] ??
+    [...new Set([agent.model, ...(agent.models ?? [])].filter((model): model is string => Boolean(model)))].join(", ");
+  const { candidates, unresolved } = resolveAgentModelChain(agent, roles);
+  const chain = candidates.length > 0 ? `${candidates.join(" → ")} → parent fallback` : "parent fallback";
+  const source = roles.agentModels[agent.name] ? "override" : "frontmatter";
+  const warn = unresolved.length > 0 ? ` (unresolved: ${unresolved.join(", ")})` : "";
+  return `[${source}: ${raw}] ${chain}${warn}`;
+}

package/extensions/runner.ts

@@ -413,7 +413,9 @@ export function getFinalOutput(messages: Message[]): string {
       if (part.type === "text" && part.text.trim()) texts.push(part.text);
     }
     if (texts.length === 0) continue;
-    return texts.join("");
+    // Join with a newline so interleaved text segments (text around toolCall
+    // parts in one message) stay separated instead of gluing "…done.Next step…".
+    return texts.join("\n");
   }
   return "";
 }

package/extensions/security.ts

@@ -565,6 +565,14 @@ export function validateExecutionRequest(
 ): ValidationError[] {
   const errors: ValidationError[] = [];
 
+  // Timeout (single/parallel/chain share one requested timeout)
+  if (options.timeout !== undefined) {
+    const t = normalizeTimeout({ requested: options.timeout });
+    if (t.error) {
+      errors.push({ field: "timeout", message: t.error });
+    }
+  }
+
   // Agent name
   if (options.agentName !== undefined) {
     if (typeof options.agentName !== "string" || options.agentName.trim().length === 0) {

package/extensions/service.ts

@@ -1,7 +1,8 @@
 import { type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type AgentConfig, getModelCandidates } from "./agents.ts";
+import { type AgentConfig } from "./agents.ts";
 import { runSubAgent, type SubAgentProgress, type SubAgentResult } from "./runner.ts";
-import { resolveModel } from "./model.ts";
+import { resolveModel, runWithModelFallback } from "./model.ts";
+import { readSubagentRoles, resolveAgentModelChain } from "./roles.ts";
 import {
   isRateLimitError,
   validateAgentTools,
@@ -42,10 +43,15 @@ export async function runNamedAgent(options: {
   signal?: AbortSignal;
   /** When true, only read-only tools are permitted regardless of agent.sandbox. */
   readOnly?: boolean;
+  /** Trusted opt-out for child cwd outside the workspace (from getTrustedConfig). */
+  allowExternalCwd?: boolean;
   onMessage?: (result: SubAgentResult) => void;
   onProgress?: (progress: SubAgentProgress) => void;
 }): Promise<SubAgentResult> {
-  const { model, attempted } = await resolveModel(getModelCandidates(options.agent), options.ctx.model, options.ctx.modelRegistry);
+  const rolesCfg = readSubagentRoles(options.ctx);
+  const agentChain = resolveAgentModelChain(options.agent, rolesCfg);
+  const resolvedModel = await resolveModel(agentChain.candidates, options.ctx.model, options.ctx.modelRegistry);
+  const { model, attempted } = resolvedModel;
   if (!model) throw new Error(`No model resolved for agent "${options.agent.name}" (tried: ${attempted.join(", ") || "none"})`);
 
   const modelRegistry = options.ctx.modelRegistry;
@@ -53,7 +59,11 @@ export async function runNamedAgent(options: {
   const authStorage = (modelRegistry as any).authStorage;
 
   // Security: validate and normalise timeout.
-  const effectiveTimeoutMs = normalizeTimeout({ requested: options.timeout }).timeoutMs;
+  const timeoutResult = normalizeTimeout({ requested: options.timeout });
+  if (timeoutResult.error) {
+    throw new Error(timeoutResult.error);
+  }
+  const effectiveTimeoutMs = timeoutResult.timeoutMs;
 
   // Parent tool names — agents without an explicit `tools` line inherit them.
   const parentToolNames = (options.ctx as any).getAllTools?.()?.map((t: { name: string }) => t.name) as string[] | undefined;
@@ -77,80 +87,55 @@ export async function runNamedAgent(options: {
 
   // Security: validate cwd (service caller must provide valid cwd).
   // The service path uses the same policy as the tool path.
-  const safeCwd = resolveSafeCwd({ workspaceRoot: options.ctx.cwd, childCwd: options.cwd });
+  const safeCwd = resolveSafeCwd({ workspaceRoot: options.ctx.cwd, childCwd: options.cwd, allowExternalCwd: options.allowExternalCwd });
   if (safeCwd.error) {
     throw new Error(safeCwd.error);
   }
 
   const contract = options.instructions?.slice(0, MAX_INSTRUCTIONS_LENGTH);
 
-  // Retry loop: rate-limit model fallback
-  const candidates = getModelCandidates(options.agent);
-  const triedModels: string[] = [];
-
-  const tryWithFallback = async (): Promise<SubAgentResult> => {
-    const remaining = candidates.filter(m => !triedModels.includes(m));
-    const isParentFallback = remaining.length === 0;
-    const fallbackResolved = await resolveModel(remaining, options.ctx.model, options.ctx.modelRegistry);
-    if (!fallbackResolved.model) {
-      throw new Error(
-        `All models rate-limited or unavailable. Tried: ${triedModels.join(" → ") || "(none)"}. ` +
-        `Remaining candidates: ${remaining.join(", ") || "none"}. ` +
-        `Parent: ${options.ctx.model?.provider}/${options.ctx.model?.id}.`,
-      );
-    }
-    const triedName = `${fallbackResolved.model!.provider}/${fallbackResolved.model!.id}`;
-    if (triedModels.includes(triedName)) {
-      // Already tried this model (e.g., all candidates unavailable
-      // and parent fallback) — no further options.
-      throw new Error(
-        `All available models exhausted. Tried: ${triedModels.join(" → ")}.`,
-      );
-    }
-    triedModels.push(triedName);
-    // Also track the raw candidate name so candidates.filter() can
-    // exclude it even when the agent uses unqualified names.
-    // Avoid duplicating when candidate name is already qualified (matchedCandidate === triedName).
-    if (fallbackResolved.matchedCandidate && fallbackResolved.matchedCandidate !== triedName) {
-      triedModels.push(fallbackResolved.matchedCandidate);
-    }
-
-    const result = await runSubAgent({
-      cwd: safeCwd.path,
-      sandbox: options.agent.sandbox === "worktree" ? "worktree" : undefined,
-      systemPrompt: contract ? `${options.agent.systemPrompt}\n\n## Task Contract\n${contract}` : options.agent.systemPrompt,
-      task: options.task,
-      tools: toolValidation.tools,
-      model: fallbackResolved.model,
-      modelRuntime,
-      authStorage,
-      modelRegistry,
-      signal: options.signal,
-      timeoutMs: effectiveTimeoutMs,
-      agentName: options.agent.name,
-      thinkingLevel: options.agent.thinking,
-      onMessage: options.onMessage,
-      onProgress: options.onProgress,
-      loadExtensions,
-      projectTrusted,
-    });
-
-    if (result.errorMessage && isRateLimitError(result.errorMessage)) {
-      // If the model that just rate-limited was the parent fallback
-      // (no remaining candidates), stop — no further options.
-      if (isParentFallback) {
+  // Retry loop: rate-limit model fallback — shared with the tool path so the
+  // triedModels bookkeeping and per-candidate `:thinking` resolution stay in
+  // one place (see runWithModelFallback in model.ts). Errors are thrown here;
+  // the caller maps them to its own response shape.
+  return runWithModelFallback<SubAgentResult>({
+    candidates: agentChain.candidates,
+    parentModel: options.ctx.model,
+    modelRegistry: options.ctx.modelRegistry,
+    thinkingByCandidate: agentChain.thinkingByCandidate,
+    defaultThinking: options.agent.thinking,
+    runAttempt: (model, thinkingLevel) =>
+      runSubAgent({
+        cwd: safeCwd.path,
+        sandbox: options.agent.sandbox === "worktree" ? "worktree" : undefined,
+        systemPrompt: contract ? `${options.agent.systemPrompt}\n\n## Task Contract\n${contract}` : options.agent.systemPrompt,
+        task: options.task,
+        tools: toolValidation.tools,
+        model,
+        modelRuntime,
+        authStorage,
+        modelRegistry,
+        signal: options.signal,
+        timeoutMs: effectiveTimeoutMs,
+        agentName: options.agent.name,
+        thinkingLevel,
+        onMessage: options.onMessage,
+        onProgress: options.onProgress,
+        loadExtensions,
+        projectTrusted,
+      }),
+    isRateLimited: (result) => Boolean(result.errorMessage && isRateLimitError(result.errorMessage)),
+    onExhausted: (reason, triedModels, remaining) => {
+      const tried = triedModels.join(" → ") || "(none)";
+      const parent = options.ctx.model ? `${options.ctx.model.provider}/${options.ctx.model.id}` : "none";
+      if (reason === "no-model") {
         throw new Error(
-          `All available models exhausted. Tried: ${triedModels.join(" → ")}.`,
+          `All models rate-limited or unavailable. Tried: ${tried}. ` +
+          `Remaining candidates: ${remaining.join(", ") || "none"}. ` +
+          `Parent: ${parent}.`,
         );
       }
-      return tryWithFallback();
-    }
-    return result;
-  };
-
-  try {
-    return await tryWithFallback();
-  } finally {
-    // No manual timeout handling needed — runSubAgent handles timeouts internally.
-  }
+      throw new Error(`All available models exhausted. Tried: ${tried}.`);
+    },
+  });
 }