@gajae-code/coding-agent 0.4.4 → 0.5.0

package/src/task/executor.ts

@@ -13,7 +13,7 @@ import { type JsonSchemaValidationIssue, validateJsonSchemaValue } from "@gajae-
 import { logger, prompt, untilAborted } from "@gajae-code/utils";
 import { AsyncJobManager } from "../async";
 import { ModelRegistry } from "../config/model-registry";
-import { resolveModelOverrideWithAuthFallback } from "../config/model-resolver";
+import { formatModelString, resolveModelOverrideWithAuthFallback } from "../config/model-resolver";
 import type { PromptTemplate } from "../config/prompt-templates";
 import { Settings } from "../config/settings";
 import { SETTINGS_SCHEMA, type SettingPath } from "../config/settings-schema";
@@ -38,7 +38,7 @@ import { jtdToJsonSchema, normalizeSchema } from "../tools/jtd-to-json-schema";
 import { type ReportFindingDetails, toReviewFinding } from "../tools/review";
 import { ToolAbortError } from "../tools/tool-errors";
 import type { EventBus } from "../utils/event-bus";
-import { buildNamedToolChoice } from "../utils/tool-choice";
+import { buildNamedToolChoiceResult } from "../utils/tool-choice";
 import type { WorkspaceTree } from "../workspace-tree";
 import { subprocessToolRegistry } from "./subprocess-tool-registry";
 import {
@@ -46,6 +46,7 @@ import {
 	type AgentProgress,
 	MAX_OUTPUT_BYTES,
 	MAX_OUTPUT_LINES,
+	type ModelSubstitutionWarning,
 	type ReviewFinding,
 	type SingleResult,
 	TASK_SUBAGENT_EVENT_CHANNEL,
@@ -627,6 +628,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 	let yieldCalled = false;
 	let pauseRequested = false;
 	let paused = false;
+	let modelSubstitutionWarning: ModelSubstitutionWarning | undefined;
+	let resolvedModelString: string | undefined;
+	let lastAssistantModelString: string | undefined;
+	let effectiveThinkingLevelForWarning: ThinkingLevel | undefined;
 
 	// Accumulate usage incrementally from message_end events (no memory for streaming events)
 	const accumulatedUsage = {
@@ -762,6 +767,14 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		return undefined;
 	};
 
+	const getMessageModelString = (message: unknown): string | undefined => {
+		if (!message || typeof message !== "object") return undefined;
+		const record = message as { provider?: unknown; model?: unknown };
+		return typeof record.provider === "string" && typeof record.model === "string"
+			? `${record.provider}/${record.model}`
+			: undefined;
+	};
+
 	const updateRecentOutputLines = () => {
 		const lines = recentOutputTail.split("\n").filter(line => line.trim());
 		progress.recentOutput = lines.slice(-8).reverse();
@@ -964,6 +977,29 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 							}
 						}
 					}
+					const assistantModel = getMessageModelString(event.message);
+					if (assistantModel) {
+						lastAssistantModelString = assistantModel;
+						if (resolvedModelString && assistantModel !== resolvedModelString && !modelSubstitutionWarning) {
+							modelSubstitutionWarning = {
+								requested: resolvedModelString,
+								effective: assistantModel,
+								reason: "assistant_model_mismatch",
+							};
+							progress.modelSubstitutionWarning = modelSubstitutionWarning;
+							activeSession?.sessionManager.appendModelChange(assistantModel, undefined, {
+								previousModel: resolvedModelString,
+								reason: modelSubstitutionWarning.reason,
+								thinkingLevel: effectiveThinkingLevelForWarning ?? null,
+							});
+							logger.warn("Subagent assistant response reported a substituted effective model", {
+								requested: resolvedModelString,
+								effective: assistantModel,
+								agent: agent.name,
+								id,
+							});
+						}
+					}
 				}
 				// Extract and accumulate usage (prefer message.usage, fallback to event.usage)
 				const messageUsage = getMessageUsage(event.message) || (event as AgentEvent & { usage?: unknown }).usage;
@@ -1090,6 +1126,8 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				thinkingLevel: resolvedThinkingLevel,
 				explicitThinkingLevel,
 				authFallbackUsed,
+				requestedModel,
+				fallbackReason,
 			} = await awaitAbortable(
 				resolveModelOverrideWithAuthFallback(
 					modelPatterns,
@@ -1099,9 +1137,18 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					options.parentSessionId,
 				),
 			);
-			if (authFallbackUsed && model) {
+			if (model) {
+				resolvedModelString = formatModelString(model);
+			}
+			if (authFallbackUsed && model && requestedModel) {
+				modelSubstitutionWarning = {
+					requested: formatModelString(requestedModel),
+					effective: formatModelString(model),
+					reason: fallbackReason ?? "auth_unavailable",
+				};
+				progress.modelSubstitutionWarning = modelSubstitutionWarning;
 				logger.warn("Subagent model has no working credentials; falling back to parent session model", {
-					requested: modelPatterns,
+					requested: modelSubstitutionWarning.requested,
 					parentModel: options.parentActiveModelPattern,
 					resolvedProvider: model.provider,
 					resolvedModel: model.id,
@@ -1113,6 +1160,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			const effectiveThinkingLevel = explicitThinkingLevel
 				? resolvedThinkingLevel
 				: (thinkingLevel ?? resolvedThinkingLevel);
+			effectiveThinkingLevelForWarning = effectiveThinkingLevel;
 
 			const sessionManager = sessionFile
 				? await awaitAbortable(SessionManager.open(sessionFile))
@@ -1174,6 +1222,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					settings: subagentSettings,
 					model,
 					thinkingLevel: effectiveThinkingLevel,
+					modelSubstitution:
+						modelSubstitutionWarning?.reason === "auth_unavailable" && requestedModel
+							? { requestedModel, reason: modelSubstitutionWarning.reason }
+							: undefined,
 					toolNames,
 					outputSchema,
 					requireYieldTool: true,
@@ -1412,7 +1464,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				await awaitAbortable(session.waitForIdle());
 			}
 
-			const reminderToolChoice = buildNamedToolChoice("yield", session.model);
+			const reminderToolChoiceResult = buildNamedToolChoiceResult("yield", session.model);
 
 			let retryCount = 0;
 			while (!paused && !yieldCalled && retryCount < MAX_YIELD_RETRIES && !abortSignal.aborted) {
@@ -1433,7 +1485,9 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					await awaitAbortable(
 						session.prompt(reminder, {
 							attribution: "agent",
-							...(isFinalRetry && reminderToolChoice ? { toolChoice: reminderToolChoice } : {}),
+							...(isFinalRetry && reminderToolChoiceResult.exactNamed && reminderToolChoiceResult.choice
+								? { toolChoice: reminderToolChoiceResult.choice }
+								: {}),
 						}),
 					);
 					await awaitAbortable(session.waitForIdle());
@@ -1466,6 +1520,14 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					error = undefined;
 				}
 			}
+			if (lastAssistantModelString && resolvedModelString && lastAssistantModelString !== resolvedModelString) {
+				modelSubstitutionWarning ??= {
+					requested: resolvedModelString,
+					effective: lastAssistantModelString,
+					reason: "assistant_model_mismatch",
+				};
+				progress.modelSubstitutionWarning = modelSubstitutionWarning;
+			}
 		} catch (err) {
 			exitCode = 1;
 			if (!abortSignal.aborted) {
@@ -1642,6 +1704,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		contextTokens: progress.contextTokens,
 		contextWindow: progress.contextWindow,
 		modelOverride,
+		modelSubstitutionWarning,
 		error: exitCode !== 0 && stderr ? stderr : undefined,
 		aborted: wasAborted,
 		abortReason: finalAbortReason,

package/src/task/fork-context-advisory.ts

@@ -0,0 +1,99 @@
+import type { ForkContextMode } from "./types";
+
+export interface ForkContextAdvisory {
+	recommendedMode: ForkContextMode;
+	reasons: string[];
+	estimatedClonedTokens: Record<ForkContextMode, number>;
+	callerModeRespected: true;
+}
+
+/**
+ * Per-mode clone budget ceilings (advisory estimates only). These bound how
+ * many parent-context tokens each mode may clone into the child; the actual
+ * cloned amount can never exceed the parent context itself.
+ */
+const CLONE_BUDGET_BY_MODE = {
+	none: 0,
+	receipt: 2000,
+	"last-turn": 4000,
+	bounded: 8000,
+	full: 15000,
+} as const satisfies Record<ForkContextMode, number>;
+
+const RECEIPT_TRIGGERS = [
+	{ pattern: /as discussed/i, reason: "prior-session-reference:as-discussed" },
+	{ pattern: /as decided/i, reason: "prior-session-reference:as-decided" },
+	{ pattern: /earlier in this session/i, reason: "prior-session-reference:earlier-in-this-session" },
+	{ pattern: /per the plan above/i, reason: "prior-session-reference:per-the-plan-above" },
+	{ pattern: /the previous review/i, reason: "prior-session-reference:the-previous-review" },
+	{ pattern: /\.gjc\/plans\//i, reason: "prior-session-reference:gjc-plans-path" },
+	{ pattern: /\.gjc\/specs\//i, reason: "prior-session-reference:gjc-specs-path" },
+] as const;
+
+const LAST_TURN_TRIGGERS = [
+	{ pattern: /the last message/i, reason: "last-turn-reference:the-last-message" },
+	{ pattern: /the previous turn/i, reason: "last-turn-reference:the-previous-turn" },
+	{ pattern: /see above/i, reason: "last-turn-reference:see-above" },
+] as const;
+
+/**
+ * Estimated tokens cloned into the child per mode: the per-mode budget
+ * ceiling, capped by the actual parent context (you can never clone more
+ * than exists). Negative parent contexts are normalized to 0.
+ */
+function estimateClonedTokens(parentContextTokens: number): Record<ForkContextMode, number> {
+	const parent = Math.max(0, parentContextTokens);
+	return {
+		none: Math.min(parent, CLONE_BUDGET_BY_MODE.none),
+		receipt: Math.min(parent, CLONE_BUDGET_BY_MODE.receipt),
+		"last-turn": Math.min(parent, CLONE_BUDGET_BY_MODE["last-turn"]),
+		bounded: Math.min(parent, CLONE_BUDGET_BY_MODE.bounded),
+		full: Math.min(parent, CLONE_BUDGET_BY_MODE.full),
+	};
+}
+
+export function adviseForkContextMode(input: {
+	assignment: string;
+	context?: string;
+	explicitMode?: ForkContextMode;
+	parentContextTokens?: number;
+}): ForkContextAdvisory {
+	const parentContextTokens = input.parentContextTokens ?? 0;
+	const estimatedClonedTokens = estimateClonedTokens(parentContextTokens);
+
+	if (input.explicitMode !== undefined) {
+		return {
+			recommendedMode: input.explicitMode,
+			reasons: ["explicit-caller-mode"],
+			estimatedClonedTokens,
+			callerModeRespected: true,
+		};
+	}
+
+	const text = `${input.assignment}\n${input.context ?? ""}`;
+	const reasons: string[] = [];
+	let recommendedMode: ForkContextMode = "none";
+
+	for (const trigger of LAST_TURN_TRIGGERS) {
+		if (trigger.pattern.test(text)) {
+			reasons.push(trigger.reason);
+			recommendedMode = "last-turn";
+		}
+	}
+
+	for (const trigger of RECEIPT_TRIGGERS) {
+		if (trigger.pattern.test(text)) {
+			reasons.push(trigger.reason);
+			if (recommendedMode === "none") {
+				recommendedMode = "receipt";
+			}
+		}
+	}
+
+	return {
+		recommendedMode,
+		reasons,
+		estimatedClonedTokens,
+		callerModeRespected: true,
+	};
+}

package/src/task/index.ts

@@ -47,11 +47,13 @@ import { generateCommitMessage } from "../utils/commit-message-generator";
 import * as git from "../utils/git";
 import { discoverAgents, filterVisibleAgents, getAgent } from "./discovery";
 import { runSubprocess } from "./executor";
+import { adviseForkContextMode } from "./fork-context-advisory";
 import { getTaskIdValidationError, validateAllocatedTaskId } from "./id";
 import { AgentOutputManager } from "./output-manager";
 import { mapWithConcurrencyLimit, Semaphore } from "./parallel";
 import { assertNoRawTaskFields, buildTaskReceipt, buildTaskRoiSummary } from "./receipt";
 import { renderResult, renderCall as renderTaskCall } from "./render";
+import { reconcileSpawnRoi } from "./roi-reconciliation";
 import { getTaskSimpleModeCapabilities, type TaskSimpleMode } from "./simple-mode";
 import { DEFAULT_SPAWN_THRESHOLD, evaluateReviewerExploreGate, evaluateSpawnGate } from "./spawn-gate";
 import {
@@ -578,6 +580,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 								runMode: message ? "message" : "resume",
 								resumeMessage: message,
 								sessionFiles: new Map([[descriptor.task.id, descriptor.sessionFile]]),
+								suppressRoiReconciliation: true,
 							},
 						);
 						const finalText = result.content.find(part => part.type === "text")?.text ?? "(no output)";
@@ -675,6 +678,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 								frozenForkSeeds,
 								{
 									sessionFiles: new Map([[uniqueId, subtaskSessionFile]]),
+									suppressRoiReconciliation: true,
 								},
 							);
 							const finalText = result.content.find(part => part.type === "text")?.text ?? "(no output)";
@@ -874,6 +878,12 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			runMode?: "initial" | "resume" | "message";
 			resumeMessage?: string;
 			sessionFiles?: ReadonlyMap<string, string | null>;
+			/**
+			 * Set for per-child async runs: the spawnPlan is carried for gate
+			 * consistency, but batch-level ROI reconciliation must not be computed
+			 * against a single child's receipts.
+			 */
+			suppressRoiReconciliation?: boolean;
 		},
 	): Promise<AgentToolResult<TaskToolDetails>> {
 		const startTime = Date.now();
@@ -1293,6 +1303,17 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				const forkContext = requestsForkContext(task)
 					? { mode: task.inheritContext, clonedTokens: forkContextSeed?.metadata.approximateTokens ?? 0 }
 					: undefined;
+				// Advisory-only recommendation (logged on the receipt); never overrides
+				// the caller's explicit inheritContext mode.
+				const advisory = adviseForkContextMode({
+					assignment: task.assignment,
+					context: sharedContext,
+					explicitMode: task.inheritContext,
+				});
+				const forkContextAdvisory = {
+					recommendedMode: advisory.recommendedMode,
+					reasons: advisory.reasons,
+				};
 				const taskSessionFile = overrides?.sessionFile ?? executionOverrides?.sessionFiles?.get(task.id) ?? null;
 				if (!isIsolated) {
 					const result = await runSubprocess({
@@ -1341,7 +1362,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						parentTelemetry: this.session.getTelemetry?.(),
 						forkContextSeed,
 					});
-					return forkContext ? { ...result, forkContext } : result;
+					return { ...result, ...(forkContext ? { forkContext } : {}), forkContextAdvisory };
 				}
 
 				const taskStart = Date.now();
@@ -1402,7 +1423,11 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						parentTelemetry: this.session.getTelemetry?.(),
 						forkContextSeed,
 					});
-					const resultWithForkContext = forkContext ? { ...result, forkContext } : result;
+					const resultWithForkContext = {
+						...result,
+						...(forkContext ? { forkContext } : {}),
+						forkContextAdvisory,
+					};
 					if (mergeMode === "branch" && resultWithForkContext.exitCode === 0) {
 						try {
 							const commitMsg =
@@ -1697,6 +1722,9 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 
 			const receipts = results.map(buildTaskReceipt);
 			const roiSummary = buildTaskRoiSummary(receipts);
+			const roiReconciliation = executionOverrides?.suppressRoiReconciliation
+				? undefined
+				: reconcileSpawnRoi(params.spawnPlan, receipts);
 			const summaries = receipts.map(r => {
 				const status = r.status === "merge_failed" ? "merge failed" : r.status;
 				return {
@@ -1739,6 +1767,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				usage: hasAggregatedUsage ? aggregatedUsage : undefined,
 				forkContextClonedTokens: forkContextClonedTokens > 0 ? forkContextClonedTokens : undefined,
 				roiSummary,
+				roiReconciliation,
 			};
 			assertNoRawTaskFields(details, "task.return.details");
 			return {

package/src/task/receipt.ts

@@ -29,6 +29,7 @@ export interface TaskResultReceipt {
 	contextTokens?: number;
 	contextWindow?: number;
 	modelOverride?: string | string[];
+	modelSubstitutionWarning?: SingleResult["modelSubstitutionWarning"];
 	usage?: SingleResult["usage"];
 	cost?: number;
 	branchName?: string;
@@ -46,6 +47,7 @@ export interface TaskResultReceipt {
 	};
 	extractedToolCounts?: Record<string, number>;
 	forkContext?: SingleResult["forkContext"];
+	forkContextAdvisory?: SingleResult["forkContextAdvisory"];
 	roi?: TaskRoi;
 }
 
@@ -77,6 +79,9 @@ function truncateText(value: string | undefined, maxChars: number): string | und
 
 function buildSafeSynopsis(raw: SingleResult, outputRef: TaskResultReceipt["outputRef"]): string {
 	const status = getStatus(raw);
+	if (raw.modelSubstitutionWarning) {
+		return `Task ${status}; requested model substituted from ${raw.modelSubstitutionWarning.requested} to ${raw.modelSubstitutionWarning.effective}.`;
+	}
 	if (raw.retryFailure) {
 		return `Task ${status}; retry stopped after attempt ${raw.retryFailure.attempt}.`;
 	}
@@ -219,6 +224,7 @@ export function buildTaskReceipt(raw: SingleResult): TaskResultReceipt {
 		contextTokens: raw.contextTokens,
 		contextWindow: raw.contextWindow,
 		modelOverride: raw.modelOverride,
+		modelSubstitutionWarning: raw.modelSubstitutionWarning,
 		usage: raw.usage,
 		cost: raw.usage?.cost.total,
 		branchName: raw.branchName,
@@ -234,6 +240,7 @@ export function buildTaskReceipt(raw: SingleResult): TaskResultReceipt {
 		review: buildReview(raw),
 		extractedToolCounts,
 		forkContext: raw.forkContext,
+		forkContextAdvisory: raw.forkContextAdvisory,
 		roi: buildTaskRoi(raw),
 	};
 }

package/src/task/render.ts

@@ -119,6 +119,10 @@ function normalizeReportFindings(value: unknown): ReportFindingDetails[] {
 	return findings;
 }
 
+function formatModelSubstitutionWarning(warning: { requested: string; effective: string }): string {
+	return `Requested model substituted: ${warning.requested} -> ${warning.effective}`;
+}
+
 function formatJsonScalar(value: unknown, _theme: Theme): string {
 	if (value === null) return "null";
 	if (typeof value === "string") {
@@ -566,6 +570,14 @@ function renderAgentProgress(
 	lines.push(statusLine);
 
 	lines.push(...renderTaskSection(progress.assignment ?? progress.task, continuePrefix, expanded, theme));
+	if (progress.modelSubstitutionWarning) {
+		lines.push(
+			`${continuePrefix}${theme.fg(
+				"warning",
+				truncateToWidth(replaceTabs(formatModelSubstitutionWarning(progress.modelSubstitutionWarning)), 90),
+			)}`,
+		);
+	}
 
 	// Current tool (if running) or most recent completed tool
 	if (progress.status === "running") {
@@ -862,9 +874,17 @@ function renderAgentResult(result: TaskResultReceipt, isLast: boolean, expanded:
 				}
 			}
 		}
-	} else {
+	} else if (!result.modelSubstitutionWarning) {
 		lines.push(...renderOutputSection(result.preview, continuePrefix, expanded, theme, 3, 12));
 	}
+	if (result.modelSubstitutionWarning) {
+		lines.push(
+			`${continuePrefix}${theme.fg(
+				"warning",
+				truncateToWidth(replaceTabs(formatModelSubstitutionWarning(result.modelSubstitutionWarning)), 90),
+			)}`,
+		);
+	}
 	if (result.roi?.lowRoi) {
 		lines.push(`${continuePrefix}${theme.fg("warning", "low ROI: produced no material contribution")}`);
 	}

package/src/task/roi-reconciliation.ts

@@ -0,0 +1,90 @@
+import type { TaskResultReceipt } from "./receipt";
+import type { SpawnPlanReceipt } from "./spawn-gate";
+
+/**
+ * Pure, advisory-only reconciliation between a spawn plan's inline-token promise
+ * and receipt-safe child outputs. These signals never change task success/failure
+ * semantics or runtime behavior; they only describe budget/ROI observations for
+ * model-facing summaries.
+ */
+export interface SpawnRoiChildReconciliation {
+	id: string;
+	inlineTokens: number;
+	maxInlineTokens: number;
+	overBudget: boolean;
+	overageTokens: number;
+	lowRoi: boolean;
+}
+
+export interface SpawnRoiReconciliation {
+	childCount: number;
+	promisedMaxInlineTokens: number;
+	children: SpawnRoiChildReconciliation[];
+	overBudgetChildIds: string[];
+	lowRoiChildIds: string[];
+	totalInlineTokens: number;
+	totalOverageTokens: number;
+	advisoryFlags: string[];
+}
+
+function estimateTextTokens(text: string | undefined): number {
+	if (!text) return 0;
+	return Math.ceil(text.length / 4);
+}
+
+/**
+ * Estimate model-facing inline cost from receipt-safe fields only. The proxy uses
+ * one token per four characters, rounded up independently for the preview and
+ * review summaries that may be inlined for the parent model.
+ */
+function estimateInlineTokens(receipt: TaskResultReceipt): number {
+	const review = receipt.review;
+	const reviewSummaryChars =
+		(review?.overallCorrectness?.length ?? 0) +
+		(review?.findings?.reduce((total, finding) => total + finding.summary.length, 0) ?? 0);
+	return estimateTextTokens(receipt.preview) + Math.ceil(reviewSummaryChars / 4);
+}
+
+export function reconcileSpawnRoi(
+	plan: SpawnPlanReceipt | undefined,
+	receipts: readonly TaskResultReceipt[],
+): SpawnRoiReconciliation | undefined {
+	if (!plan) return undefined;
+
+	const children = receipts.map(receipt => {
+		const inlineTokens = estimateInlineTokens(receipt);
+		const overageTokens = Math.max(0, inlineTokens - plan.maxInlineTokens);
+		return {
+			id: receipt.id,
+			inlineTokens,
+			maxInlineTokens: plan.maxInlineTokens,
+			overBudget: overageTokens > 0,
+			overageTokens,
+			lowRoi: Boolean(receipt.roi?.lowRoi),
+		};
+	});
+	const overBudgetChildIds = children
+		.filter(child => child.overBudget)
+		.map(child => child.id)
+		.toSorted();
+	const lowRoiChildIds = children
+		.filter(child => child.lowRoi)
+		.map(child => child.id)
+		.toSorted();
+	const advisoryFlags = [
+		...(overBudgetChildIds.length > 0 ? ["over-inline-budget"] : []),
+		...(lowRoiChildIds.length > 0 ? ["low-roi-children"] : []),
+		...(children.length > 0 && lowRoiChildIds.length === children.length ? ["all-children-low-roi"] : []),
+	];
+
+	return {
+		childCount: children.length,
+		promisedMaxInlineTokens: plan.maxInlineTokens,
+		children,
+		overBudgetChildIds,
+		lowRoiChildIds,
+		totalInlineTokens: children.reduce((total, child) => total + child.inlineTokens, 0),
+		totalOverageTokens: children.reduce((total, child) => total + child.overageTokens, 0),
+		advisoryFlags,
+	};
+}

package/src/task/types.ts

@@ -4,6 +4,7 @@ import { $env } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import { isValidTaskId, TASK_ID_DESCRIPTION } from "./id";
 import type { TaskResultReceipt } from "./receipt";
+import type { SpawnRoiReconciliation } from "./roi-reconciliation";
 import { getTaskSimpleModeCapabilities, type TaskSimpleMode } from "./simple-mode";
 import type { SpawnPlanReceipt } from "./spawn-gate";
 import type { NestedRepoPatch } from "./worktree";
@@ -214,6 +215,12 @@ export interface AgentDefinition {
 	filePath?: string;
 }
 
+export interface ModelSubstitutionWarning {
+	requested: string;
+	effective: string;
+	reason: "auth_unavailable" | "assistant_model_mismatch";
+}
+
 /** Progress tracking for a single agent */
 export interface AgentProgress {
 	index: number;
@@ -246,6 +253,7 @@ export interface AgentProgress {
 	cost: number;
 	durationMs: number;
 	modelOverride?: string | string[];
+	modelSubstitutionWarning?: ModelSubstitutionWarning;
 	/** Data extracted by registered subprocess tool handlers (keyed by tool name) */
 	extractedToolData?: Record<string, unknown[]>;
 	/**
@@ -305,6 +313,7 @@ export interface SingleResult {
 	/** Model's context window in tokens, when known. */
 	contextWindow?: number;
 	modelOverride?: string | string[];
+	modelSubstitutionWarning?: ModelSubstitutionWarning;
 	error?: string;
 	aborted?: boolean;
 	abortReason?: string;
@@ -337,6 +346,11 @@ export interface SingleResult {
 	outputMeta?: { lineCount: number; charCount: number; byteSize?: number; sha256?: string };
 	/** Fork-context seed accounting for this subagent, when inherited parent context was cloned. */
 	forkContext?: { mode: ForkContextMode; clonedTokens: number };
+	/**
+	 * Advisory fork-context mode recommendation for this task (logged only;
+	 * never changes the actual mode selection).
+	 */
+	forkContextAdvisory?: { recommendedMode: ForkContextMode; reasons: string[] };
 }
 
 /** Tool details for TUI rendering */
@@ -356,6 +370,7 @@ export interface TaskToolDetails {
 		/** Advisory ids for terminal children that spent tokens without detectable output/review/changes. */
 		lowRoiChildIds: string[];
 	};
+	roiReconciliation?: SpawnRoiReconciliation;
 	progress?: AgentProgress[];
 	async?: {
 		state: "running" | "paused" | "queued" | "completed" | "failed";

package/src/thinking-metadata.ts

@@ -0,0 +1,51 @@
+export type ThinkingLevelValue = "inherit" | "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+/**
+ * Metadata used to render thinking selector values in the coding-agent UI.
+ *
+ * This module is intentionally provider/native-free so schema generation can
+ * import settings metadata before native addons have been built in CI.
+ */
+export interface ThinkingLevelMetadata {
+	value: ThinkingLevelValue;
+	label: string;
+	description: string;
+}
+
+const THINKING_LEVEL_METADATA: Record<ThinkingLevelValue, ThinkingLevelMetadata> = {
+	inherit: {
+		value: "inherit",
+		label: "inherit",
+		description: "Inherit session default",
+	},
+	off: { value: "off", label: "off", description: "No reasoning" },
+	minimal: {
+		value: "minimal",
+		label: "min",
+		description: "Very brief reasoning (~1k tokens)",
+	},
+	low: { value: "low", label: "low", description: "Light reasoning (~2k tokens)" },
+	medium: {
+		value: "medium",
+		label: "medium",
+		description: "Moderate reasoning (~8k tokens)",
+	},
+	high: { value: "high", label: "high", description: "Deep reasoning (~16k tokens)" },
+	xhigh: {
+		value: "xhigh",
+		label: "xhigh",
+		description: "Maximum reasoning (~32k tokens)",
+	},
+	max: {
+		value: "max",
+		label: "max",
+		description: "Opus maximum reasoning",
+	},
+};
+
+/**
+ * Returns display metadata for a thinking selector.
+ */
+export function getThinkingLevelMetadata(level: ThinkingLevelValue): ThinkingLevelMetadata {
+	return THINKING_LEVEL_METADATA[level];
+}