jeo-code 0.1.0 → 0.4.4

package/src/agent/step-budget.ts

@@ -0,0 +1,232 @@
+/**
+ * StepBudget — gjc-style flexible step budgeting ("retry flow") for the agent loop.
+ *
+ * Replaces the bare `step <= maxSteps` counter with a budget that EXTENDS itself
+ * while the turn is demonstrably making progress (recent tool calls succeeding on
+ * distinct targets) and fails fast into consolidation when it is stalled. Mirrors
+ * gjc's provider retry budgets: a base budget, a bounded number of extensions, an
+ * absolute hard cap, and explicit fail-fast classes (a stalled window — too many
+ * failures or no distinct targets — never earns an extension).
+ *
+ * The existing engine guards (MAX_REPEAT identical calls, MAX_FAILURES consecutive
+ * failures, parse-bounce salvage) remain the early fail-fast layer; this module
+ * only governs what happens when the step counter reaches the current limit.
+ */
+
+export interface StepBudgetConfig {
+  /** Initial step budget (the caller's `maxSteps`). */
+  baseSteps: number;
+  /** Steps granted per extension. */
+  extensionSteps: number;
+  /** How many times the budget may extend (0 = legacy fixed counter). */
+  maxExtensions: number;
+  /** Absolute ceiling no extension may cross. */
+  hardCap: number;
+  /** Recent tool-call window scored for progress. */
+  windowSize: number;
+  /** Required ok-ratio in the window to earn an extension. */
+  minProgressRatio: number;
+  /** Required distinct call signatures in the window (anti-spin). */
+  minDistinct: number;
+}
+
+export interface ExtensionDecision {
+  extend: boolean;
+  /** Human-readable reason — surfaced as an onNotice/onBudget line. */
+  reason: string;
+  /** The (possibly new) current limit after the decision. */
+  limit: number;
+}
+
+type EnvLike = Record<string, string | undefined>;
+
+function envNum(env: EnvLike, key: string, dflt: number, min: number, max: number): number {
+  // `key` is the legacy JEO_* name; the JEO_* spelling is preferred when both are set.
+  const raw = env[key.replace(/^JEO_/, "JEO_")] ?? env[key];
+  if (raw === undefined || raw === "") return dflt;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return dflt;
+  return Math.max(min, Math.min(max, Math.trunc(n)));
+}
+
+/**
+ * Resolve the effective budget config: defaults ← env (`JEO_STEP_*`) ← caller overrides.
+ * Defaults keep the flow ON for the main agent (2 extensions, half-budget each, 3× cap);
+ * bounded delegation (task/team subagents) passes `{ maxExtensions: 0 }` so a parent's
+ * step contract stays exact.
+ */
+export function resolveStepBudgetConfig(
+  baseSteps: number,
+  env: EnvLike = process.env,
+  overrides?: Partial<StepBudgetConfig>,
+): StepBudgetConfig {
+  const base = Math.max(1, Math.trunc(baseSteps));
+  const cfg: StepBudgetConfig = {
+    baseSteps: base,
+    extensionSteps: envNum(env, "JEO_STEP_EXTENSION_SIZE", Math.max(4, Math.ceil(base / 2)), 1, 100),
+    maxExtensions: envNum(env, "JEO_STEP_EXTENSIONS", 2, 0, 8),
+    hardCap: envNum(env, "JEO_STEP_HARD_CAP", base * 3, base, base * 10),
+    windowSize: envNum(env, "JEO_STEP_WINDOW", 8, 2, 32),
+    minProgressRatio: 0.5,
+    minDistinct: 2,
+  };
+  const merged = { ...cfg, ...overrides };
+  // Sanity: the cap can never undercut the base budget.
+  merged.baseSteps = Math.max(1, Math.trunc(merged.baseSteps));
+  merged.hardCap = Math.max(merged.baseSteps, Math.trunc(merged.hardCap));
+  merged.maxExtensions = Math.max(0, Math.trunc(merged.maxExtensions));
+  merged.extensionSteps = Math.max(1, Math.trunc(merged.extensionSteps));
+  merged.windowSize = Math.max(2, Math.trunc(merged.windowSize));
+  return merged;
+}
+
+/** True when `key` carries a non-empty value in `env`. */
+function envSet(env: EnvLike, key: string): boolean {
+  const raw = env[key.replace(/^JEO_/, "JEO_")] ?? env[key];
+  return raw !== undefined && raw !== "";
+}
+
+/**
+ * Dynamic (process-driven) budget — the default when the caller passes no explicit
+ * `--max-steps`: there is no SMALL hardcoded step ceiling. The budget starts at a
+ * rolling base (`JEO_STEP_BASE`, default 24) and keeps extending itself for as long
+ * as the recent tool window shows real progress; only a stalled window declines the
+ * extension, at which point the loop dynamically CONSOLIDATES a final wrap-up
+ * instead of dying at a fixed count.
+ *
+ * Termination is still GUARANTEED: extensions are unlimited in count, but the
+ * absolute ceiling defaults to `DYNAMIC_HARD_CAP` (600 steps) instead of Infinity.
+ * An unbounded ceiling turned every hole in the progress heuristic into a literal
+ * infinite loop (e.g. a model cycling successful reads forever); a large finite cap
+ * keeps long autonomous runs alive while converting a pathological spin into a
+ * consolidation wrap-up. Setting `JEO_STEP_EXTENSIONS` / `JEO_STEP_HARD_CAP`
+ * restores a fully bounded budget; caller overrides win over both.
+ */
+export const DYNAMIC_HARD_CAP = 600;
+
+export function dynamicStepBudgetConfig(
+  env: EnvLike = process.env,
+  overrides?: Partial<StepBudgetConfig>,
+): StepBudgetConfig {
+  const base = envNum(env, "JEO_STEP_BASE", 24, 1, 10_000);
+  const dynamic: Partial<StepBudgetConfig> = {};
+  if (!envSet(env, "JEO_STEP_EXTENSIONS")) dynamic.maxExtensions = Number.POSITIVE_INFINITY;
+  if (!envSet(env, "JEO_STEP_HARD_CAP")) dynamic.hardCap = Math.max(base, DYNAMIC_HARD_CAP);
+  return resolveStepBudgetConfig(base, env, { ...dynamic, ...overrides });
+}
+
+/** The step limit a dynamic turn starts from — seeds the `step N/M` display before
+ *  the engine's onBudget extensions grow the denominator. */
+export function initialDynamicStepLimit(env: EnvLike = process.env): number {
+  return dynamicStepBudgetConfig(env).baseSteps;
+}
+
+/**
+ * Fixed-size hash of a tool-call signature (two interleaved FNV-1a streams).
+ * Signature strings embed the full JSON arguments — a `write` call carries the
+ * whole file body — so per-turn bookkeeping (the novelty `seen` set, the scoring
+ * window, the engine's repeat/cycle guards) stores this digest instead. Bounds a
+ * long turn's signature memory at O(steps × ~14 bytes) without changing any
+ * equality semantics the guards rely on.
+ */
+export function hashSignature(s: string): string {
+  let h1 = 0x811c9dc5 | 0;
+  let h2 = 0x811c9dc5 | 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193);
+    h2 = Math.imul(h2 ^ (c + i), 0x01000193);
+  }
+  return (h1 >>> 0).toString(36) + "." + (h2 >>> 0).toString(36);
+}
+
+export class StepBudget {
+  private readonly cfg: StepBudgetConfig;
+  private readonly window: { signature: string; success: boolean }[] = [];
+  private extensions = 0;
+  private currentLimit: number;
+  /** Every signature executed this turn — basis of the novelty rule. */
+  private readonly seen = new Set<string>();
+  /** Never-seen-before signatures recorded since the last granted extension.
+   *  An extension requires ≥ 1: a window that merely CYCLES through previously
+   *  executed calls (read A, read B, read A, …) is a spin, not progress, even
+   *  when every call succeeds and the distinct-count check passes. */
+  private novelSinceExtension = 0;
+
+  constructor(cfg: StepBudgetConfig) {
+    this.cfg = cfg;
+    this.currentLimit = Math.min(cfg.baseSteps, cfg.hardCap);
+  }
+
+  /** The current step limit (base + granted extensions). */
+  limit(): number {
+    return this.currentLimit;
+  }
+
+  /** Extensions granted so far. */
+  extensionsUsed(): number {
+    return this.extensions;
+  }
+
+  /** Record an executed tool call (ring-buffered to the scoring window).
+   *  Stored as a fixed-size digest — see `hashSignature` (memory bound). */
+  record(signature: string, success: boolean): void {
+    const sig = hashSignature(signature);
+    if (!this.seen.has(sig)) {
+      this.seen.add(sig);
+      this.novelSinceExtension++;
+    }
+    this.window.push({ signature: sig, success });
+    if (this.window.length > this.cfg.windowSize) this.window.shift();
+  }
+
+  /** Progress over the recent window: ok count, total, distinct signatures. */
+  progress(): { ok: number; total: number; distinct: number } {
+    const ok = this.window.filter(r => r.success).length;
+    const distinct = new Set(this.window.map(r => r.signature)).size;
+    return { ok, total: this.window.length, distinct };
+  }
+
+  /**
+   * Called when the step counter reaches the current limit. Grants a bounded
+   * extension when the recent window shows real progress; otherwise declines
+   * with an explicit fail-fast reason (the loop then consolidates).
+   */
+  tryExtend(): ExtensionDecision {
+    const decline = (why: string): ExtensionDecision => ({
+      extend: false,
+      reason: why,
+      limit: this.currentLimit,
+    });
+    if (this.cfg.maxExtensions <= 0) return decline("step extensions disabled");
+    if (this.extensions >= this.cfg.maxExtensions) {
+      return decline(`extension budget exhausted (${this.extensions}/${this.cfg.maxExtensions})`);
+    }
+    if (this.currentLimit >= this.cfg.hardCap) {
+      return decline(`hard step cap ${this.cfg.hardCap} reached`);
+    }
+    const p = this.progress();
+    if (p.total < 2) return decline(`not enough recent tool activity (${p.total} call(s))`);
+    const ratio = p.ok / p.total;
+    if (ratio < this.cfg.minProgressRatio || p.distinct < this.cfg.minDistinct) {
+      return decline(
+        `no recent progress (${p.ok}/${p.total} ok, ${p.distinct} distinct target(s))`,
+      );
+    }
+    if (this.novelSinceExtension < 1) {
+      return decline(
+        `no novel tool calls since the last extension (cycling through ${p.distinct} repeated target(s))`,
+      );
+    }
+    this.extensions++;
+    this.novelSinceExtension = 0;
+    this.currentLimit = Math.min(this.currentLimit + this.cfg.extensionSteps, this.cfg.hardCap);
+    return {
+      extend: true,
+      reason:
+        `progress detected (${p.ok}/${p.total} recent tools ok, ${p.distinct} targets) — ` +
+        `step budget extended to ${this.currentLimit} (extension ${this.extensions}/${this.cfg.maxExtensions})`,
+      limit: this.currentLimit,
+    };
+  }
+}

package/src/agent/subagents.ts

@@ -2,15 +2,19 @@
  * Subagent role registry (gjc role-agent parity: executor / planner / architect /
  * critic). A "subagent" is the executor tool-loop driven with a role-specific
  * system prompt, model, step budget, and toolset. The registry is pure data so
- * it can be listed in the TUI (`/agents`) and consumed by `joc team` without
+ * it can be listed in the TUI (`/agents`) and consumed by `jeo team` without
  * importing any provider or I/O code.
  *
  * Read-only roles (planner/architect/critic) get a mutation-free toolset so a
  * review/plan lane physically cannot edit the repo, mirroring gjc's read-only
  * role agents.
  */
-import { DEFAULT_TOOLS, executorSystemPrompt, type ToolHandler } from "./engine";
+import { DEFAULT_TOOLS, TOOL_PROTOCOL, READONLY_TOOL_PROTOCOL, WORKING_DISCIPLINE, type ToolHandler } from "./engine";
 import type { Config } from "./state";
+import architectPrompt from "../prompts/agents/architect.md" with { type: "text" };
+import criticPrompt from "../prompts/agents/critic.md" with { type: "text" };
+import executorPrompt from "../prompts/agents/executor.md" with { type: "text" };
+import plannerPrompt from "../prompts/agents/planner.md" with { type: "text" };
 
 export interface SubagentRole {
   /** Stable id used in config + `/agents <id>`. */
@@ -23,6 +27,16 @@ export interface SubagentRole {
   readOnly: boolean;
   /** Default tool-loop step budget for this role. */
   defaultMaxSteps: number;
+  /** Role-specific prompt template. */
+  prompt: string;
+  /** Required markers that must appear in done.reason. */
+  requiredDoneMarkers?: string[];
+  /** When set on a MUTATING role, bash is wrapped so EVERY shell segment must
+   *  start with one of these prefixes (after stripping leading env-assignments /
+   *  `sudo`); anything else is rejected. The registry definition IS the runtime
+   *  constraint — no config plumbing. Undefined = unconstrained bash. Read-only
+   *  roles drop bash entirely regardless. (plan/gjc-inheritance.md cycle 10, B5) */
+  bashAllowedPrefixes?: string[];
 }
 
 /** The four bundled subagent roles. `executor` is the only mutating role. */
@@ -33,6 +47,8 @@ export const SUBAGENT_ROLES: readonly SubagentRole[] = [
     description: "Bounded implementation, refactors, fixes, and verification-ready edits.",
     readOnly: false,
     defaultMaxSteps: 15,
+    prompt: executorPrompt,
+    requiredDoneMarkers: ["Summary:", "Changed Files:", "Verification:"],
   },
   {
     id: "planner",
@@ -40,6 +56,17 @@ export const SUBAGENT_ROLES: readonly SubagentRole[] = [
     description: "Read-only sequencing, acceptance criteria, risks, and handoff shape.",
     readOnly: true,
     defaultMaxSteps: 10,
+    prompt: plannerPrompt,
+    requiredDoneMarkers: [
+      "Summary:",
+      "In Scope:",
+      "Out of Scope:",
+      "File-level Changes:",
+      "Sequencing:",
+      "Acceptance Criteria:",
+      "Verification:",
+      "Risks:",
+    ],
   },
   {
     id: "architect",
@@ -47,6 +74,14 @@ export const SUBAGENT_ROLES: readonly SubagentRole[] = [
     description: "Read-only architecture and code review with severity-rated findings.",
     readOnly: true,
     defaultMaxSteps: 10,
+    prompt: architectPrompt,
+    requiredDoneMarkers: [
+      "Summary:",
+      "Findings:",
+      "Recommendations:",
+      "Architectural Status:",
+      "Code Review Recommendation:",
+    ],
   },
   {
     id: "critic",
@@ -54,20 +89,64 @@ export const SUBAGENT_ROLES: readonly SubagentRole[] = [
     description: "Read-only plan critic; approves only actionable, verifiable plans.",
     readOnly: true,
     defaultMaxSteps: 8,
+    prompt: criticPrompt,
+    requiredDoneMarkers: ["Justification:"],
   },
 ];
 
 const DEFAULT_ROLE_ID = "executor";
 
+/** Generic prompt template for CONFIG-DECLARED custom roles (no per-role .md
+ *  bundled). Uses the same {{…}} variables as the bundled templates, so the
+ *  whole role pipeline stays template-driven rather than hardcoded. */
+const CUSTOM_ROLE_PROMPT = `You are the {{ROLE_TITLE}} subagent: {{ROLE_DESCRIPTION}}
+
+{{TOOL_PROTOCOL}}
+
+Work strictly within your assignment. When finished, reply
+{"tool":"done","arguments":{"reason":"Summary: <what you found/did>"}}.`;
+
+/**
+ * SYSTEM-driven role registry: config.subagents entries that DECLARE a role
+ * identity (a \`prompt\`, \`title\`, or \`description\`) under an id that is not
+ * bundled become first-class roles — no code change needed to add one. Bare
+ * model/steps pins on unknown ids are NOT roles (typo safety). Safety default:
+ * a custom role is READ-ONLY unless it explicitly sets \`readOnly: false\`.
+ */
+export function rolesFromConfig(config: Pick<Config, "subagents">): SubagentRole[] {
+  const custom: SubagentRole[] = [];
+  for (const [rawId, entry] of Object.entries(config.subagents ?? {})) {
+    const id = normalizeRoleId(rawId);
+    if (!id || SUBAGENT_ROLES.some(r => r.id === id)) continue;
+    if (!entry || (entry.prompt === undefined && entry.title === undefined && entry.description === undefined)) continue;
+    const title = entry.title ?? id.charAt(0).toUpperCase() + id.slice(1);
+    custom.push({
+      id,
+      title,
+      description: entry.description ?? `Custom role "${id}" (declared in config.subagents).`,
+      readOnly: entry.readOnly ?? true,
+      defaultMaxSteps: typeof entry.maxSteps === "number" && entry.maxSteps > 0 ? entry.maxSteps : 12,
+      prompt: (entry.prompt ?? CUSTOM_ROLE_PROMPT).replaceAll("{{ROLE_DESCRIPTION}}", entry.description ?? title),
+    });
+  }
+  return custom;
+}
+
+/** Bundled roles + config-declared custom roles (the full live registry). */
+export function allSubagentRoles(config?: Pick<Config, "subagents">): SubagentRole[] {
+  return config ? [...SUBAGENT_ROLES, ...rolesFromConfig(config)] : [...SUBAGENT_ROLES];
+}
+
 /** Normalize loosely-typed role input (case-insensitive, trimmed). */
 export function normalizeRoleId(input: string | undefined | null): string {
   return (input ?? "").trim().toLowerCase();
 }
 
-/** Look up a role by id (case-insensitive). Returns undefined when unknown. */
-export function getSubagentRole(id: string | undefined | null): SubagentRole | undefined {
+/** Look up a role by id (case-insensitive) across the bundled registry and —
+ *  when a config is supplied — config-declared custom roles. */
+export function getSubagentRole(id: string | undefined | null, config?: Pick<Config, "subagents">): SubagentRole | undefined {
   const want = normalizeRoleId(id);
-  return SUBAGENT_ROLES.find(r => r.id === want);
+  return allSubagentRoles(config).find(r => r.id === want);
 }
 
 /** The default role (`executor`) used when none is specified. */
@@ -81,41 +160,112 @@ export type SubagentConfig = NonNullable<Config["subagents"]>;
 /** Per-role model override → falls back to the global default model. */
 export function resolveSubagentModel(roleId: string, config: Pick<Config, "defaultModel" | "subagents">): string {
   const entry = config.subagents?.[normalizeRoleId(roleId)];
-  return entry?.model ?? config.defaultModel;
+  return entry?.model || config.defaultModel;
 }
 
 /** Per-role step budget → config override, else the role default, else 15. */
 export function resolveSubagentMaxSteps(roleId: string, config: Pick<Config, "subagents">): number {
   const entry = config.subagents?.[normalizeRoleId(roleId)];
   if (typeof entry?.maxSteps === "number" && entry.maxSteps > 0) return entry.maxSteps;
-  return getSubagentRole(roleId)?.defaultMaxSteps ?? 15;
+  return getSubagentRole(roleId, config)?.defaultMaxSteps ?? 15;
+}
+
+function renderRolePrompt(template: string, role: SubagentRole): string {
+  return template
+    .replaceAll("{{TOOL_PROTOCOL}}", `${TOOL_PROTOCOL}\n\n${WORKING_DISCIPLINE}`)
+    .replaceAll("{{READONLY_TOOL_PROTOCOL}}", READONLY_TOOL_PROTOCOL)
+    .replaceAll("{{ROLE_TITLE}}", role.title)
+    .trim();
+}
+
+export function validateSubagentDoneReason(role: SubagentRole, reason: string | undefined): { ok: boolean; missing?: string[] } {
+  const trimmed = (reason ?? "").trim();
+  if (!trimmed) return { ok: false, missing: ["done.reason"] };
+  if (role.id === "critic") {
+    const verdicts = ["[OKAY]", "[ITERATE]", "[REJECT]"];
+    const hasVerdict = verdicts.some(marker => trimmed.startsWith(marker));
+    const missing = [
+      ...(hasVerdict ? [] : ["[OKAY]|[ITERATE]|[REJECT]"]),
+      ...((role.requiredDoneMarkers ?? []).filter(marker => !trimmed.includes(marker))),
+    ];
+    return { ok: missing.length === 0, missing };
+  }
+  const missing = (role.requiredDoneMarkers ?? []).filter(marker => !trimmed.includes(marker));
+  return { ok: missing.length === 0, missing };
 }
 
-/** Build a role-specific executor system prompt; read-only roles get a no-mutation directive. */
+/** Build a role-specific system prompt from its dedicated template. */
 export function subagentSystemPrompt(role: SubagentRole): string {
-  const base = executorSystemPrompt(`${role.title} subagent — ${role.description}`);
-  if (!role.readOnly) return base;
-  return (
-    base +
-    `\n\nYou are a READ-ONLY ${role.title}. Do not create or modify files; ` +
-    `use read / find / search (and read-only bash) only, then report your findings via done.`
-  );
+  return renderRolePrompt(role.prompt, role);
+}
+
+/**
+ * True when EVERY shell segment of `command` starts with one of `prefixes`
+ * (after stripping leading env-assignments and a leading `sudo`). Splitting on
+ * `; && || |` means a chained `… && rm -rf` cannot smuggle an un-vetted command
+ * past a single allowed head. Command substitution (`$(…)`, backticks) can't be
+ * statically vetted, so it is rejected outright. Empty allowlist = unconstrained.
+ */
+export function bashCommandAllowed(command: string, prefixes: string[]): boolean {
+  if (prefixes.length === 0) return true;
+  if (/[`]|\$\(/.test(command)) return false; // un-vettable command substitution
+  const matches = (seg: string, p: string) =>
+    seg === p || seg.startsWith(p + " ") || seg.startsWith(p + "\t");
+  for (const raw of command.split(/(?:&&|\|\||[;|])/)) {
+    let seg = raw.trim();
+    if (seg === "") continue;
+    seg = seg
+      .replace(/^(?:\w+=(?:"[^"]*"|'[^']*'|\S+)\s+)+/, "") // FOO=bar BAZ=qux cmd
+      .replace(/^sudo\s+/, "")
+      .trim();
+    if (seg === "" || !prefixes.some(p => matches(seg, p))) return false;
+  }
+  return true;
 }
 
-/** Toolset for a role: read-only roles drop the mutating tools (write/edit). */
+/**
+ * Toolset for a role:
+ *  - Read-only roles drop ALL mutating tools (write/edit AND bash) so a
+ *    review/plan lane physically cannot change the repo.
+ *  - A mutating role with `bashAllowedPrefixes` gets bash replaced by a
+ *    prefix-checking wrapper (registry definition = runtime constraint).
+ *  - Otherwise the full default toolset (unconstrained bash) is returned.
+ */
 export function subagentToolset(role: SubagentRole): Record<string, ToolHandler> {
-  if (!role.readOnly) return DEFAULT_TOOLS;
-  const ro: Record<string, ToolHandler> = {};
-  for (const [name, handler] of Object.entries(DEFAULT_TOOLS)) {
-    if (name === "write" || name === "edit") continue;
-    ro[name] = handler;
+  if (role.readOnly) {
+    const MUTATING = new Set(["write", "edit", "bash"]);
+    const ro: Record<string, ToolHandler> = {};
+    for (const [name, handler] of Object.entries(DEFAULT_TOOLS)) {
+      if (MUTATING.has(name)) continue;
+      ro[name] = handler;
+    }
+    return ro;
   }
-  return ro;
+  const prefixes = role.bashAllowedPrefixes;
+  if (prefixes && prefixes.length > 0) {
+    const inner = DEFAULT_TOOLS.bash;
+    const guarded: Record<string, ToolHandler> = { ...DEFAULT_TOOLS };
+    guarded.bash = async (a, cwd) => {
+      const command = String(a.command ?? a.cmd ?? "");
+      if (!bashCommandAllowed(command, prefixes)) {
+        return {
+          success: false,
+          output: "",
+          error:
+            `bash rejected for role '${role.id}': every command segment must start with one of [${prefixes.join(", ")}]. ` +
+            `Received: ${command.trim().slice(0, 120)}`,
+        };
+      }
+      return inner(a, cwd);
+    };
+    return guarded;
+  }
+  return DEFAULT_TOOLS;
 }
 
-/** All role ids (for `/agents` autocomplete + validation). */
-export function subagentRoleIds(): string[] {
-  return SUBAGENT_ROLES.map(r => r.id);
+/** All role ids — bundled + config-declared (for autocomplete + validation). */
+export function subagentRoleIds(config?: Pick<Config, "subagents">): string[] {
+  return allSubagentRoles(config).map(r => r.id);
 }
 
 /** Parse a `/agents <role> maxSteps <n>` value → positive int, else undefined. */
@@ -129,10 +279,21 @@ export function parseMaxSteps(input: string | undefined): number | undefined {
  * maxSteps). Pure — does not mutate `config`. Unknown roles are rejected by the
  * caller via `getSubagentRole`; this helper trusts the id it is given.
  */
+export type ThinkLevelValue = "minimal" | "low" | "medium" | "high" | "xhigh";
+
+/** Per-role reasoning level → explicit role override, else undefined (= INHERIT
+ *  the global thinkingLevel at call time — gjc's "(inherit)" semantics). */
+export function resolveSubagentThinking(
+  roleId: string,
+  config: Pick<Config, "subagents">,
+): ThinkLevelValue | undefined {
+  return config.subagents?.[normalizeRoleId(roleId)]?.thinking;
+}
+
 export function withSubagentSetting(
   config: Pick<Config, "subagents">,
   roleId: string,
-  patch: { model?: string; maxSteps?: number },
+  patch: { model?: string; maxSteps?: number; thinking?: ThinkLevelValue },
 ): SubagentConfig {
   const id = normalizeRoleId(roleId);
   const subs: SubagentConfig = { ...(config.subagents ?? {}) };
@@ -147,3 +308,39 @@ export function clearSubagentSetting(config: Pick<Config, "subagents">, roleId:
   delete subs[id];
   return subs;
 }
+
+/** One pickable apply-target: the global default or a subagent role. */
+export interface ApplyTargetChoice {
+  /** "default" or a subagent role id. */
+  value: string;
+  label: string;
+  /** Right-aligned hint: the target's CURRENT model (so the picker doubles as a viewer). */
+  hint: string;
+}
+
+/**
+ * Choices for the "apply picked model to…" picker shown after an interactive
+ * model selection (gjc parity: picking a model also lets you pick WHO uses it).
+ * The hint shows each target's current model, so the same picker doubles as a
+ * read-and-change panel for existing role assignments. Pure — testable.
+ */
+export function applyTargetChoices(
+  config: Pick<Config, "defaultModel" | "subagents" | "thinkingLevel">,
+): ApplyTargetChoice[] {
+  const roleThink = (id: string): string => {
+    const t = resolveSubagentThinking(id, config);
+    return t ? ` (${t})` : " (inherit)";
+  };
+  return [
+    {
+      value: "default",
+      label: "default — every session",
+      hint: `${config.defaultModel} (${config.thinkingLevel ?? "medium"})`,
+    },
+    ...allSubagentRoles(config).map(role => ({
+      value: role.id,
+      label: `subagent ${role.id} — ${role.title}`,
+      hint: resolveSubagentModel(role.id, config) + (config.subagents?.[role.id]?.model ? "" : " (default)") + roleThink(role.id),
+    })),
+  ];
+}