@gajae-code/coding-agent 0.4.3 → 0.4.5

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({
@@ -1324,6 +1345,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 							progressMap.set(index, {
 								...structuredClone(progress),
 							});
+							AsyncJobManager.instance()?.recordSubagentProgress(task.id, progress);
 							emitProgress();
 						},
 						authStorage: this.session.authStorage,
@@ -1340,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();
@@ -1384,6 +1406,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 							progressMap.set(index, {
 								...structuredClone(progress),
 							});
+							AsyncJobManager.instance()?.recordSubagentProgress(task.id, progress);
 							emitProgress();
 						},
 						authStorage: this.session.authStorage,
@@ -1400,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 =
@@ -1695,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 {
@@ -1737,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

@@ -46,6 +46,7 @@ export interface TaskResultReceipt {
 	};
 	extractedToolCounts?: Record<string, number>;
 	forkContext?: SingleResult["forkContext"];
+	forkContextAdvisory?: SingleResult["forkContextAdvisory"];
 	roi?: TaskRoi;
 }
 
@@ -234,6 +235,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

@@ -690,6 +690,20 @@ function renderAgentProgress(
 	return lines;
 }
 
+/**
+ * Public wrapper to render a single subagent's live `AgentProgress` for the
+ * `subagent` await panel. Reuses the internal task-progress renderer so the
+ * await panel stays at parity with the inline task panel.
+ */
+export function renderSubagentLiveProgress(
+	progress: AgentProgress,
+	expanded: boolean,
+	theme: Theme,
+	spinnerFrame?: number,
+): string[] {
+	return renderAgentProgress(progress, true, expanded, theme, spinnerFrame);
+}
+
 /**
  * Render review result with combined verdict + findings in tree structure.
  */

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";
@@ -337,6 +338,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 +362,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/tools/ask.ts

@@ -175,6 +175,7 @@ interface UIContext {
 			onLeft?: () => void;
 			onRight?: () => void;
 			helpText?: string;
+			customInput?: { optionLabel: string; onSubmit: (text: string) => void };
 		},
 	): Promise<string | undefined>;
 	editor(
@@ -194,6 +195,7 @@ async function askSingleQuestion(
 ): Promise<SelectionResult> {
 	const { recommended, timeout, signal, initialSelection, navigation, scrollTitleRows } = options;
 	const doneLabel = getDoneOptionLabel();
+	const otherOptionLabel = options.otherOptionLabel ?? OTHER_OPTION;
 	let selectedOptions = [...(initialSelection?.selectedOptions ?? [])];
 	let customInput = initialSelection?.customInput;
 	let timedOut = false;
@@ -202,11 +204,20 @@ async function askSingleQuestion(
 		prompt: string,
 		optionsToShow: string[],
 		initialIndex?: number,
-	): Promise<{ choice: string | undefined; timedOut: boolean; navigation?: "back" | "forward" }> => {
+	): Promise<{
+		choice: string | undefined;
+		timedOut: boolean;
+		navigation?: "back" | "forward";
+		inlineInput?: string;
+	}> => {
 		let timeoutTriggered = false;
 		const onTimeout = () => {
 			timeoutTriggered = true;
 		};
+		// Inline custom input: the TUI selector keeps the question and option
+		// list on screen and collects the "Other" text below the list, instead
+		// of swapping to a separate editor screen that hides the question.
+		let inlineInput: string | undefined;
 		let navigationAction: "back" | "forward" | undefined;
 		const baseHelpText = navigation
 			? "up/down navigate  enter select  ←/→ question  esc cancel"
@@ -222,6 +233,12 @@ async function askSingleQuestion(
 			scrollTitleRows,
 			onTimeout,
 			helpText,
+			customInput: {
+				optionLabel: otherOptionLabel,
+				onSubmit: (text: string) => {
+					inlineInput = text;
+				},
+			},
 			onLeft: navigation?.allowBack
 				? () => {
 						navigationAction = "back";
@@ -240,16 +257,17 @@ async function askSingleQuestion(
 		if (!timeoutTriggered && choice === undefined && typeof timeout === "number") {
 			timeoutTriggered = Date.now() - startMs >= timeout;
 		}
-		return { choice, timedOut: timeoutTriggered, navigation: navigationAction };
+		return { choice, timedOut: timeoutTriggered, navigation: navigationAction, inlineInput };
 	};
 
+	// Fallback for UI contexts that don't support inline custom input (they
+	// resolve the "Other" label without invoking customInput.onSubmit).
 	const promptForCustomInput = async (): Promise<{ input: string | undefined }> => {
 		const dialogOptions = signal ? { signal } : undefined;
 		const showCustomInput = () => ui.editor("Enter your response:", undefined, dialogOptions, { promptStyle: true });
 		const input = signal ? await untilAborted(signal, showCustomInput) : await showCustomInput();
 		return { input };
 	};
-	const otherOptionLabel = options.otherOptionLabel ?? OTHER_OPTION;
 
 	const promptWithProgress = navigation?.progressText ? `${question} (${navigation.progressText})` : question;
 	if (multi) {
@@ -278,6 +296,7 @@ async function askSingleQuestion(
 				choice,
 				timedOut: selectTimedOut,
 				navigation: arrowNavigation,
+				inlineInput,
 			} = await selectOption(`${prefix}${promptWithProgress}`, opts, cursorIndex);
 
 			if (arrowNavigation) {
@@ -297,11 +316,11 @@ async function askSingleQuestion(
 					timedOut = true;
 					break;
 				}
-				const customResult = await promptForCustomInput();
-				if (customResult.input === undefined) {
+				const input = inlineInput !== undefined ? inlineInput : (await promptForCustomInput()).input;
+				if (input === undefined) {
 					break;
 				}
-				customInput = customResult.input;
+				customInput = input;
 				break;
 			}
 
@@ -353,6 +372,7 @@ async function askSingleQuestion(
 			choice,
 			timedOut: selectTimedOut,
 			navigation: arrowNavigation,
+			inlineInput,
 		} = await selectOption(promptWithProgress, optionsWithNavigation, initialIndex);
 		timedOut = selectTimedOut;
 
@@ -365,12 +385,12 @@ async function askSingleQuestion(
 			}
 		} else if (choice === otherOptionLabel) {
 			if (!selectTimedOut) {
-				const customResult = await promptForCustomInput();
-				if (customResult.input !== undefined) {
-					customInput = customResult.input;
+				const input = inlineInput !== undefined ? inlineInput : (await promptForCustomInput()).input;
+				if (input !== undefined) {
+					customInput = input;
 					selectedOptions = [];
 				}
-				// If editor was dismissed (undefined), keep prior selectedOptions/customInput intact
+				// If input was dismissed (undefined), keep prior selectedOptions/customInput intact
 			}
 		} else {
 			selectedOptions = [stripRecommendedSuffix(choice)];

package/src/tools/index.ts

@@ -403,7 +403,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		toolNames && toolNames.length > 0 ? [...new Set(toolNames.map(name => name.toLowerCase()))] : undefined;
 	const goalEnabled = session.settings.get("goal.enabled");
 	const goalStateToolNames = [...GOAL_MODE_TOOL_NAMES];
-	if (goalEnabled && session.getGoalRuntime !== undefined && requestedTools && !requestedTools.includes("goal")) {
+	if (goalEnabled && requestedTools && !requestedTools.includes("goal")) {
 		requestedTools = [...requestedTools, "goal"];
 	}
 	if (goalEnabled && requestedTools) {
@@ -482,7 +482,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		allToolsByRequestName.set(name.toLowerCase(), [name, factory]);
 	}
 	const isToolAllowed = (name: string) => {
-		if (name === "goal") return goalEnabled && session.getGoalRuntime !== undefined;
+		if (name === "goal") return goalEnabled;
 		if (goalStateToolNames.includes(name as (typeof GOAL_MODE_TOOL_NAMES)[number])) return goalEnabled;
 		if (name === "lsp") return enableLsp && session.settings.get("lsp.enabled");
 		if (name === "bash") return true;

package/src/tools/renderers.ts

@@ -29,6 +29,7 @@ import { resolveToolRenderer } from "./resolve";
 import { searchToolRenderer } from "./search";
 import { searchToolBm25Renderer } from "./search-tool-bm25";
 import { sshToolRenderer } from "./ssh";
+import { subagentToolRenderer } from "./subagent-render";
 import { todoWriteToolRenderer } from "./todo-write";
 import { writeToolRenderer } from "./write";
 
@@ -66,6 +67,7 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	resolve: resolveToolRenderer as ToolRenderer,
 	search_tool_bm25: searchToolBm25Renderer as ToolRenderer,
 	ssh: sshToolRenderer as ToolRenderer,
+	subagent: subagentToolRenderer as ToolRenderer,
 	task: taskToolRenderer as ToolRenderer,
 	todo_write: todoWriteToolRenderer as ToolRenderer,
 	github: githubToolRenderer as ToolRenderer,