@bastani/atomic 0.9.13-alpha.1 → 0.9.13-alpha.3

package/dist/builtin/subagents/src/runs/inprocess/runtime-support/nested-api.ts

@@ -25,9 +25,7 @@ export {
 	MAX_NESTED_STEPS,
 	MAX_PROCESSED_NESTED_EVENTS,
 	NESTED_EVENTS_DIR,
-	NESTED_RUNS_DIR,
 	resolveInheritedNestedRouteFromEnv,
-	resolveNestedAsyncDir,
 	resolveNestedParentAddressFromEnv,
 	resolveNestedRouteFromEnv,
 	validateNestedRouteShape,
@@ -41,11 +39,6 @@ export {
 export {
 	attachRootChildrenToSteps,
 	hasLiveNestedDescendants,
-	isTopLevelAsyncDir,
-	nestedArtifactEnv,
-	nestedResultsPath,
-	nestedSummaryFromAsyncStatus,
-	updateAsyncJobNestedProjection,
 	updateForegroundNestedProjection,
 } from "./nested-projection.ts";
 export type { NestedRunMatch, NestedRunResolutionScope } from "./nested-registry.ts";

package/dist/builtin/subagents/src/runs/inprocess/runtime-support/nested-core.ts

@@ -7,7 +7,6 @@ import { registerInProcessNestedRoute } from "../nested-routing.ts";
 import { isSafeNestedPathId, type NestedPathEntry } from "./nested-paths.ts";
 
 export const NESTED_EVENTS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
-export const NESTED_RUNS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-runs");
 export const ROUTE_FILE = "route.json";
 export const REGISTRY_FILE = "registry.json";
 export const MAX_NESTED_EVENT_BYTES = 64 * 1024;
@@ -163,7 +162,6 @@ function cleanupOldSubdirectories(root: string, maxAgeDays: number): void {
 
 export function cleanupOldNestedRuntimeDirs(maxAgeDays: number): void {
 	cleanupOldSubdirectories(NESTED_EVENTS_DIR, maxAgeDays);
-	cleanupOldSubdirectories(NESTED_RUNS_DIR, maxAgeDays);
 }
 
 export function resolveNestedRouteFromEnv(_env: NodeJS.ProcessEnv = process.env): NestedRoute | undefined {
@@ -180,14 +178,6 @@ export function resolveNestedParentAddressFromEnv(
 	return undefined;
 }
 
-export function resolveNestedAsyncDir(rootRunId: string, run: NestedRunSummary): string | undefined {
-	if (!run.asyncDir) return undefined;
-	const resolved = path.resolve(run.asyncDir);
-	const nestedRoot = path.resolve(NESTED_RUNS_DIR, rootRunId, run.id);
-	const relative = path.relative(nestedRoot, resolved);
-	return resolved === nestedRoot || (!relative.startsWith("..") && !path.isAbsolute(relative)) ? resolved : undefined;
-}
-
 export function clampNumber(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }

package/dist/builtin/subagents/src/runs/inprocess/runtime-support/nested-projection.ts

@@ -1,15 +1,5 @@
-import * as path from "node:path";
-import { APP_NAME } from "@bastani/atomic";
-import {
-	ASYNC_DIR,
-	type AsyncJobState,
-	type AsyncStatus,
-	type NestedRunSummary,
-	RESULTS_DIR,
-	type SubagentRunMode,
-	type SubagentState,
-} from "../../../shared/types.ts";
-import { assertSafeId, containedPath, MAX_NESTED_CHILDREN, MAX_NESTED_STEPS, NESTED_RUNS_DIR } from "./nested-core.ts";
+import type { NestedRunSummary, SubagentState } from "../../../shared/types.ts";
+import { MAX_NESTED_CHILDREN } from "./nested-core.ts";
 import { projectNestedEvents } from "./nested-registry.ts";
 import { terminal } from "./nested-sanitize.ts";
 
@@ -19,9 +9,7 @@ export function attachRootChildrenToSteps<T extends { children?: NestedRunSummar
 	children: NestedRunSummary[] | undefined,
 ): void {
 	if (!steps?.length) return;
-	for (const step of steps) {
-		step.children = undefined;
-	}
+	for (const step of steps) step.children = undefined;
 	if (!children?.length) return;
 	for (const child of children) {
 		if (child.parentRunId !== rootRunId || child.parentStepIndex === undefined) continue;
@@ -35,13 +23,6 @@ export function attachRootChildrenToSteps<T extends { children?: NestedRunSummar
 	}
 }
 
-export function updateAsyncJobNestedProjection(job: AsyncJobState): void {
-	if (!job.nestedRoute) return;
-	const registry = projectNestedEvents(job.nestedRoute);
-	job.nestedChildren = registry.children;
-	attachRootChildrenToSteps(job.asyncId, job.steps, registry.children);
-}
-
 export function updateForegroundNestedProjection(
 	control: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never,
 ): void {
@@ -59,91 +40,3 @@ export function hasLiveNestedDescendants(children: NestedRunSummary[] | undefine
 	}
 	return false;
 }
-
-export function nestedSummaryFromAsyncStatus(
-	status: AsyncStatus,
-	asyncDir: string,
-	fallback: {
-		id: string;
-		parentRunId: string;
-		parentStepIndex?: number;
-		depth: number;
-		path?: Array<{ runId: string; stepIndex?: number; agent?: string }>;
-		mode?: SubagentRunMode;
-		ts: number;
-	},
-): NestedRunSummary {
-	return {
-		id: status.runId || fallback.id,
-		parentRunId: fallback.parentRunId,
-		...(fallback.parentStepIndex !== undefined ? { parentStepIndex: fallback.parentStepIndex } : {}),
-		depth: fallback.depth,
-		path: fallback.path ?? [
-			{
-				runId: fallback.parentRunId,
-				...(fallback.parentStepIndex !== undefined ? { stepIndex: fallback.parentStepIndex } : {}),
-			},
-		],
-		asyncDir,
-		...(status.pid ? { pid: status.pid } : {}),
-		...(status.sessionId ? { sessionId: status.sessionId } : {}),
-		mode: status.mode ?? fallback.mode,
-		state: status.state,
-		...(status.currentStep !== undefined ? { currentStep: status.currentStep } : {}),
-		...(status.chainStepCount !== undefined ? { chainStepCount: status.chainStepCount } : {}),
-		...(status.activityState ? { activityState: status.activityState } : {}),
-		...(status.lastActivityAt !== undefined ? { lastActivityAt: status.lastActivityAt } : {}),
-		...(status.currentTool ? { currentTool: status.currentTool } : {}),
-		...(status.currentToolStartedAt !== undefined ? { currentToolStartedAt: status.currentToolStartedAt } : {}),
-		...(status.currentPath ? { currentPath: status.currentPath } : {}),
-		...(status.turnCount !== undefined ? { turnCount: status.turnCount } : {}),
-		...(status.toolCount !== undefined ? { toolCount: status.toolCount } : {}),
-		...(status.totalTokens ? { totalTokens: status.totalTokens } : {}),
-		...(status.startedAt !== undefined ? { startedAt: status.startedAt } : { startedAt: fallback.ts }),
-		...(status.endedAt !== undefined ? { endedAt: status.endedAt } : {}),
-		lastUpdate: status.lastUpdate ?? fallback.ts,
-		...(status.sessionFile ? { sessionFile: status.sessionFile } : {}),
-		...(status.steps?.length
-			? {
-					steps: status.steps
-						.map((step) => ({
-							agent: step.agent,
-							status: step.status,
-							...(step.sessionFile ? { sessionFile: step.sessionFile } : {}),
-							...(step.activityState ? { activityState: step.activityState } : {}),
-							...(step.lastActivityAt !== undefined ? { lastActivityAt: step.lastActivityAt } : {}),
-							...(step.currentTool ? { currentTool: step.currentTool } : {}),
-							...(step.currentToolStartedAt !== undefined
-								? { currentToolStartedAt: step.currentToolStartedAt }
-								: {}),
-							...(step.currentPath ? { currentPath: step.currentPath } : {}),
-							...(step.turnCount !== undefined ? { turnCount: step.turnCount } : {}),
-							...(step.toolCount !== undefined ? { toolCount: step.toolCount } : {}),
-							...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),
-							...(step.endedAt !== undefined ? { endedAt: step.endedAt } : {}),
-							...(step.error ? { error: step.error } : {}),
-						}))
-						.slice(0, MAX_NESTED_STEPS),
-				}
-			: {}),
-	};
-}
-
-export function nestedArtifactEnv(rootRunId: string, parentRunId: string): Record<string, string> {
-	const envPrefix = APP_NAME.toUpperCase();
-	return {
-		[`${envPrefix}_SUBAGENT_NESTED_ROOT_RUN_ID`]: rootRunId,
-		[`${envPrefix}_SUBAGENT_NESTED_PARENT_RUN_ID`]: parentRunId,
-	};
-}
-
-export function isTopLevelAsyncDir(asyncDir: string): boolean {
-	const resolved = path.resolve(asyncDir);
-	return containedPath(ASYNC_DIR, resolved) && !containedPath(NESTED_RUNS_DIR, resolved);
-}
-
-export function nestedResultsPath(rootRunId: string, id: string): string {
-	assertSafeId("rootRunId", rootRunId);
-	assertSafeId("id", id);
-	return path.join(RESULTS_DIR, "nested", rootRunId, `${id}.json`);
-}

package/dist/builtin/subagents/src/runs/inprocess/runtime-support/nested-sanitize.ts

@@ -91,10 +91,6 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
 		depth: Math.min(Math.max(0, clampNumber(raw.depth) ?? 0), MAX_NESTED_DEPTH),
 		path: pathParts,
 		state: sanitizeState(raw.state, "running"),
-		...(stringValue(raw.asyncDir, 2048) ? { asyncDir: stringValue(raw.asyncDir, 2048) } : {}),
-		...(clampNumber(raw.pid) !== undefined && clampNumber(raw.pid)! > 0 && Number.isInteger(clampNumber(raw.pid))
-			? { pid: clampNumber(raw.pid) }
-			: {}),
 		...(stringValue(raw.sessionId, 256) ? { sessionId: stringValue(raw.sessionId, 256) } : {}),
 		...(stringValue(raw.sessionFile, 2048) ? { sessionFile: stringValue(raw.sessionFile, 2048) } : {}),
 		...(stringValue(raw.intercomTarget, 256) ? { intercomTarget: stringValue(raw.intercomTarget, 256) } : {}),
@@ -109,7 +105,7 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
 			: {}),
 		...(stringValue(raw.controlInbox, 2048) ? { controlInbox: stringValue(raw.controlInbox, 2048) } : {}),
 		...(stringValue(raw.capabilityToken, 128) ? { capabilityToken: stringValue(raw.capabilityToken, 128) } : {}),
-		...(raw.mode === "single" || raw.mode === "parallel" || raw.mode === "chain" ? { mode: raw.mode } : {}),
+		...(raw.mode === "single" || raw.mode === "parallel" ? { mode: raw.mode } : {}),
 		...(stringValue(raw.agent, 128) ? { agent: stringValue(raw.agent, 128) } : {}),
 		...(Array.isArray(raw.agents)
 			? {
@@ -119,8 +115,6 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
 						.slice(0, MAX_NESTED_STEPS),
 				}
 			: {}),
-		...(clampNumber(raw.currentStep) !== undefined ? { currentStep: clampNumber(raw.currentStep) } : {}),
-		...(clampNumber(raw.chainStepCount) !== undefined ? { chainStepCount: clampNumber(raw.chainStepCount) } : {}),
 		...(raw.activityState === "active_long_running" || raw.activityState === "needs_attention"
 			? { activityState: raw.activityState }
 			: {}),

package/dist/builtin/subagents/src/runs/shared/intercom-group.ts

@@ -1,8 +1,5 @@
 import { randomUUID } from "node:crypto";
-
-interface OrchestrationCarrier {
-	orchestrationContext?: { intercomGroup?: string } | undefined;
-}
+import { readRuntimeIntercomGroup } from "@bastani/atomic";
 
 /** Normalize agent-serialized auto-group sentinels without changing real group names. */
 export function normalizeAutoGroupSentinel(group: string | true | undefined): string | true | undefined {
@@ -11,15 +8,34 @@ export function normalizeAutoGroupSentinel(group: string | true | undefined): st
 	return sentinel === "true" || sentinel === "auto" ? true : group;
 }
 
-/** Read the inherited stage/session intercom group from the extension context (never from process.env). */
+/** Runtime joins are intentionally inherited before static child policy and stage context. */
+function runtimeIntercomGroup(sessionId: string | undefined): string | undefined {
+	return readRuntimeIntercomGroup(sessionId);
+}
+
+interface OrchestrationCarrier {
+	orchestrationContext?: { intercomGroup?: string } | undefined;
+	subagentPolicy?: { intercomGroup?: string } | undefined;
+	sessionManager?: { getSessionId(): string } | undefined;
+}
+
+/**
+ * Read the live joined group before the admitted child or static stage group. The runtime env
+ * entry is a deliberate exception to the no-process-env rule for admission capabilities: it
+ * carries only the current group so children launched after `join` follow their parent.
+ */
 export function inheritedIntercomGroup(ctx: OrchestrationCarrier | undefined): string | undefined {
+	const runtimeGroup = runtimeIntercomGroup(ctx?.sessionManager?.getSessionId());
+	if (runtimeGroup !== undefined) return runtimeGroup;
+	const policyGroup = ctx?.subagentPolicy?.intercomGroup;
+	if (typeof policyGroup === "string" && policyGroup.trim().length > 0) return policyGroup.trim();
 	const group = ctx?.orchestrationContext?.intercomGroup;
 	return typeof group === "string" && group.trim().length > 0 ? group.trim() : undefined;
 }
 
 /**
- * Resolve the intercom group for a spawned subagent child. Precedence:
- * explicit task/parallel/chain group > inherited current-session (stage) group.
+ * Resolve the intercom group for a spawned subagent child. Explicit task group
+ * takes precedence over the inherited current-session group.
  * `true` resolves to `sharedAutoGroup` (a single UUID minted once per parallel
  * set) so every child in the set shares one isolated group. Returns undefined
  * when nothing applies, so the child inherits env/config/default itself.

package/dist/builtin/subagents/src/runs/shared/parallel-utils.ts

@@ -1,89 +1,3 @@
-import type { CodexFastModeResolvedSettings, CodexFastModeScope } from "@bastani/atomic";
-import type { ModelAttempt } from "../../shared/types.ts";
-
-export interface RunnerSubagentStep {
-	agent: string;
-	task: string;
-	phase?: string;
-	label?: string;
-	outputName?: string;
-	structured?: boolean;
-	intercomGroup?: string;
-	cwd?: string;
-	model?: string;
-	thinking?: string;
-	fastMode?: boolean;
-	modelFastModes?: Record<string, boolean>;
-	modelCandidates?: string[];
-	modelAttempts?: ModelAttempt[];
-	codexFastModeSettings?: CodexFastModeResolvedSettings;
-	codexFastModeScope?: CodexFastModeScope;
-	tools?: string[];
-	extensions?: string[];
-	mcpDirectTools?: string[];
-	systemPrompt?: string | null;
-	systemPromptMode?: "append" | "replace";
-	inheritProjectContext: boolean;
-	inheritSkills: boolean;
-	skills?: string[];
-	outputPath?: string;
-	outputMode?: "inline" | "file-only";
-	sessionFile?: string;
-	maxSubagentDepth?: number;
-	workflowStageSubagentGuard?: boolean;
-	structuredOutput?: {
-		schema: import("../../shared/types.ts").JsonSchemaObject;
-		schemaPath: string;
-		outputPath: string;
-	};
-	structuredOutputSchema?: import("../../shared/types.ts").JsonSchemaObject;
-}
-
-export interface ParallelStepGroup {
-	parallel: RunnerSubagentStep[];
-	concurrency?: number;
-	failFast?: boolean;
-	worktree?: boolean;
-}
-
-export interface DynamicRunnerGroup {
-	expand: import("../../shared/settings.ts").DynamicExpandSpec;
-	parallel: RunnerSubagentStep;
-	collect: import("../../shared/settings.ts").DynamicCollectSpec;
-	concurrency?: number;
-	failFast?: boolean;
-	phase?: string;
-	label?: string;
-}
-
-export type RunnerStep = RunnerSubagentStep | ParallelStepGroup | DynamicRunnerGroup;
-
-export function isParallelGroup(step: RunnerStep): step is ParallelStepGroup {
-	return "parallel" in step && Array.isArray(step.parallel);
-}
-
-export function isDynamicRunnerGroup(step: RunnerStep): step is DynamicRunnerGroup {
-	return (
-		"expand" in step &&
-		"collect" in step &&
-		"parallel" in step &&
-		!Array.isArray((step as { parallel?: unknown }).parallel)
-	);
-}
-
-export function flattenSteps(steps: RunnerStep[]): RunnerSubagentStep[] {
-	const flat: RunnerSubagentStep[] = [];
-	for (const step of steps) {
-		if (isParallelGroup(step)) {
-			for (const task of step.parallel) flat.push(task);
-		} else if (isDynamicRunnerGroup(step)) {
-		} else {
-			flat.push(step);
-		}
-	}
-	return flat;
-}
-
 export async function mapConcurrent<T, R>(
 	items: T[],
 	limit: number,

package/dist/builtin/subagents/src/runs/shared/subagent-control.ts

@@ -8,7 +8,7 @@ import type {
 } from "../../shared/types.ts";
 
 const CONTROL_EVENT_TYPES: ControlEventType[] = ["active_long_running", "needs_attention"];
-const CONTROL_NOTIFICATION_CHANNELS: ControlNotificationChannel[] = ["event", "async", "intercom"];
+const CONTROL_NOTIFICATION_CHANNELS: ControlNotificationChannel[] = ["event", "intercom"];
 const DEFAULT_NOTIFY_ON: ControlEventType[] = ["active_long_running", "needs_attention"];
 
 export const DEFAULT_CONTROL_CONFIG: ResolvedControlConfig = {

package/dist/builtin/subagents/src/runs/shared/worktree.ts

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { createGitEnvironment } from "@bastani/atomic";
+import { createChildProcessEnvironment, createGitEnvironment } from "@bastani/atomic";
 import { performPostCreationSetup } from "./worktree-post-create.js";
 import { findCanonicalGitRoot } from "./worktree-root.js";
 export interface WorktreeSetup {
@@ -70,9 +70,13 @@ interface RepoState {
 	baseCommit: string;
 	baseRef: string;
 }
+
 const DEFAULT_WORKTREE_SETUP_HOOK_TIMEOUT_MS = 30000;
 function runGit(cwd: string, args: string[]): GitResult {
-	const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf-8", env: createGitEnvironment() });
+	const result = spawnSync("git", ["-C", cwd, ...args], {
+		encoding: "utf-8",
+		env: createGitEnvironment({}, createChildProcessEnvironment()),
+	});
 	return {
 		stdout: result.stdout ?? "",
 		stderr: result.stderr ?? "",
@@ -268,6 +272,7 @@ function runWorktreeSetupHook(hook: ResolvedWorktreeSetupHook, input: WorktreeSe
 		cwd: input.worktreePath,
 		encoding: "utf-8",
 		input: JSON.stringify(input),
+		env: createChildProcessEnvironment(),
 		timeout: hook.timeoutMs,
 		shell: false,
 	});

package/dist/builtin/subagents/src/shared/formatters.ts

@@ -2,12 +2,8 @@
  * Formatting utilities for display output
  */
 
-import * as fs from "node:fs";
-import * as path from "node:path";
 import { splitKnownThinkingSuffix, THINKING_LEVELS } from "./model-info.ts";
-import type { ChainStep } from "./settings.ts";
-import { isDynamicParallelStep, isParallelStep } from "./settings.ts";
-import type { SingleResult, Usage } from "./types.ts";
+import type { Usage } from "./types.ts";
 
 /**
  * Format token count with k suffix for large numbers
@@ -18,13 +14,11 @@ export function formatTokens(n: number): string {
 
 export function formatModelThinking(model?: string, thinking?: string, fastMode?: boolean): string {
 	const parsed = model ? splitKnownThinkingSuffix(model) : undefined;
-	let displayModel = parsed?.baseModel ?? model;
+	// Keep the full `provider/model` id so subagent lines read exactly like the
+	// main chat's model display; only a known thinking suffix is split off.
+	const displayModel = parsed?.baseModel ?? model;
 	const explicitThinking = THINKING_LEVELS.find((level) => level === thinking?.trim());
 	const displayThinking = parsed?.thinkingSuffix ? parsed.thinkingSuffix.slice(1) : explicitThinking;
-	if (displayModel) {
-		const slashIdx = displayModel.lastIndexOf("/");
-		if (slashIdx !== -1) displayModel = displayModel.slice(slashIdx + 1);
-	}
 	const parts = [displayModel, displayThinking ? `thinking ${displayThinking}` : undefined].filter(Boolean);
 	if (fastMode && parts.length > 0) parts.push("fast");
 	return parts.join(" · ");
@@ -33,7 +27,7 @@ export function formatModelThinking(model?: string, thinking?: string, fastMode?
 /**
  * Format usage statistics into a compact string
  */
-export function formatUsage(u: Usage, model?: string): string {
+export function formatUsage(u: Usage): string {
 	const parts: string[] = [];
 	if (u.turns) parts.push(`${u.turns} turn${u.turns > 1 ? "s" : ""}`);
 	if (u.input) parts.push(`in:${formatTokens(u.input)}`);
@@ -41,7 +35,6 @@ export function formatUsage(u: Usage, model?: string): string {
 	if (u.cacheRead) parts.push(`R${formatTokens(u.cacheRead)}`);
 	if (u.cacheWrite) parts.push(`W${formatTokens(u.cacheWrite)}`);
 	if (u.cost) parts.push(`$${u.cost.toFixed(4)}`);
-	if (model) parts.push(model);
 	return parts.join(" ");
 }
 
@@ -59,55 +52,6 @@ export function formatDuration(ms: number): string {
 	return `${seconds}s`;
 }
 
-/**
- * Build a summary string for a completed/failed chain
- */
-export function buildChainSummary(
-	steps: ChainStep[],
-	results: SingleResult[],
-	chainDir: string,
-	status: "completed" | "failed",
-	failedStep?: { index: number; error: string },
-): string {
-	const stepNames = steps
-		.map((step) =>
-			isParallelStep(step)
-				? `parallel[${step.parallel.length}]`
-				: isDynamicParallelStep(step)
-					? `expand:${step.parallel.agent}`
-					: step.agent,
-		)
-		.join(" → ");
-
-	const totalDuration = results.reduce((sum, r) => sum + (r.progress?.durationMs || 0), 0);
-	const durationStr = formatDuration(totalDuration);
-
-	const progressPath = path.join(chainDir, "progress.md");
-	const hasProgress = fs.existsSync(progressPath);
-	const allSkills = new Set<string>();
-	for (const r of results) {
-		if (r.skills) {
-			for (const skill of r.skills) allSkills.add(skill);
-		}
-	}
-	const skillsLine = allSkills.size > 0 ? `🔧 Skills: ${[...allSkills].join(", ")}` : "";
-
-	if (status === "completed") {
-		const stepWord = results.length === 1 ? "step" : "steps";
-		return `✅ Chain completed: ${stepNames} (${results.length} ${stepWord}, ${durationStr})${skillsLine ? `\n${skillsLine}` : ""}
-
-📋 Progress: ${hasProgress ? progressPath : "(none)"}
-📁 Artifacts: ${chainDir}`;
-	} else {
-		const stepInfo = failedStep ? ` at step ${failedStep.index + 1}` : "";
-		const errorInfo = failedStep?.error ? `: ${failedStep.error}` : "";
-		return `❌ Chain failed${stepInfo}${errorInfo}${skillsLine ? `\n${skillsLine}` : ""}
-
-📋 Progress: ${hasProgress ? progressPath : "(none)"}
-📁 Artifacts: ${chainDir}`;
-	}
-}
-
 /**
  * Format a tool call for display
  */

package/dist/builtin/subagents/src/shared/model-resolution.ts

@@ -0,0 +1,78 @@
+/**
+ * Resolution of a selected model candidate id to a concrete registry model.
+ *
+ * `buildModelCandidates` yields `provider/model[:thinking]` strings. Those
+ * strings alone never reach the child session: `createAgentSession` takes a
+ * `Model<Api>` object, and when no model is supplied it restores the model
+ * persisted in the session file. For a fork-context child that file is a copy
+ * of the parent's, so the parent's model silently won. Resolving the selected
+ * candidate to a real model here is what lets the configured model be handed
+ * to the child session instead.
+ *
+ * The lookup semantics deliberately mirror the SDK's own fallback-entry
+ * resolution (`resolveFallbackModel`), so the primary candidate and the
+ * fallback candidates handed to the same session agree on what a candidate
+ * string means.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai/compat";
+import { splitKnownThinkingSuffix, THINKING_LEVELS, type ThinkingLevel } from "./model-info.ts";
+
+/** Registry surface needed to resolve a candidate; satisfied by `ctx.modelRegistry`. */
+export interface CandidateModelLookup {
+	getAvailable(): Model<Api>[];
+	find(provider: string, modelId: string): Model<Api> | undefined;
+	hasConfiguredAuth(model: Model<Api>): boolean;
+}
+
+/** A candidate string resolved to a concrete model and its requested thinking level. */
+export interface ResolvedCandidateModel {
+	model: Model<Api>;
+	thinkingLevel?: ThinkingLevel;
+}
+
+/**
+ * Resolve one `provider/model[:thinking]` candidate id against the registry.
+ * Returns `undefined` when the candidate names no usable model, which leaves
+ * the caller on its previous behavior rather than failing the run.
+ */
+export type CandidateModelResolver = (candidateId: string) => ResolvedCandidateModel | undefined;
+
+function thinkingLevelFromSuffix(suffix: string): ThinkingLevel | undefined {
+	if (!suffix) return undefined;
+	const level = suffix.slice(1);
+	return THINKING_LEVELS.find((known) => known === level);
+}
+
+export function resolveCandidateModel(
+	candidateId: string,
+	lookup: CandidateModelLookup,
+	preferredProvider?: string,
+): ResolvedCandidateModel | undefined {
+	const trimmed = candidateId.trim();
+	if (!trimmed) return undefined;
+	const { baseModel, thinkingSuffix } = splitKnownThinkingSuffix(trimmed);
+	const thinkingLevel = thinkingLevelFromSuffix(thinkingSuffix);
+	const slash = baseModel.indexOf("/");
+	if (slash < 0) {
+		const available = lookup.getAvailable().filter((entry) => entry.id === baseModel);
+		const model =
+			available.find((entry) => entry.provider === preferredProvider) ??
+			(available.length === 1 ? available[0] : undefined);
+		if (!model) return undefined;
+		return thinkingLevel === undefined ? { model } : { model, thinkingLevel };
+	}
+	const provider = baseModel.slice(0, slash);
+	const modelId = baseModel.slice(slash + 1);
+	const model = lookup.find(provider, modelId);
+	if (!model || !lookup.hasConfiguredAuth(model)) return undefined;
+	return thinkingLevel === undefined ? { model } : { model, thinkingLevel };
+}
+
+/** Bind a registry and the parent's provider into a reusable candidate resolver. */
+export function createCandidateModelResolver(
+	lookup: CandidateModelLookup,
+	preferredProvider?: string,
+): CandidateModelResolver {
+	return (candidateId: string) => resolveCandidateModel(candidateId, lookup, preferredProvider);
+}