@gajae-code/coding-agent 0.4.4 → 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({
@@ -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

@@ -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/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/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/subagent-render.ts

@@ -73,7 +73,11 @@ function renderSubagentSnapshot(
 		for (const al of snapshot.assignment.split("\n")) lines.push(`    ${theme.fg("toolOutput", replaceTabs(al))}`);
 	}
 
-	if (snapshot.progress) {
+	// Defense in depth: the producer only attaches `progress` when a live
+	// producer exists (subagent.ts #liveProgressFields), but the renderer
+	// also honors an explicit `liveProgressAvailable: false` so stale retained
+	// progress can never resurrect a live panel (AC5).
+	if (snapshot.progress && snapshot.liveProgressAvailable !== false) {
 		// Live streaming panel (full task-panel parity), indented under the header.
 		for (const pl of renderSubagentLiveProgress(snapshot.progress, expanded, theme, spinnerFrame)) {
 			lines.push(`  ${pl}`);
@@ -142,6 +146,11 @@ export const subagentToolRenderer = {
 				);
 
 				const lines: string[] = [header];
+				// Discoverability: the inline panel is a bounded preview; the session
+				// observer (ctrl+s) streams the full per-subagent message history.
+				if (runningCount > 0) {
+					lines.push(`  ${theme.fg("dim", "(ctrl+s to observe sessions)")}`);
+				}
 				for (const snapshot of subagents) {
 					lines.push(...renderSubagentSnapshot(snapshot, expanded, theme, options.spinnerFrame));
 				}

package/src/utils/title-generator.ts

@@ -12,7 +12,7 @@ import titleSystemPrompt from "../prompts/system/title-system.md" with { type: "
 
 const TITLE_SYSTEM_PROMPT = prompt.render(titleSystemPrompt);
 
-const DEFAULT_TERMINAL_TITLE = "π";
+const DEFAULT_TERMINAL_TITLE = "GJC";
 const TERMINAL_TITLE_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
 
 const MAX_INPUT_CHARS = 2000;
@@ -20,6 +20,13 @@ const TITLE_MAX_TOKENS = 30;
 const REASONING_SAFE_MAX_TOKENS = 1024;
 const SET_TITLE_TOOL_NAME = "set_title";
 
+// Some models (notably cursor/composer-*) ignore the forced set_title tool call
+// and instead emit a long free-text narrative. Without the tool call we fall back
+// to the plain text, so cap its length: a real 3-6 word title never exceeds these.
+// Beyond the cap we treat the response as a non-title hallucination and reject it.
+const MAX_TITLE_CHARS = 80;
+const MAX_TITLE_WORDS = 12;
+
 const setTitleTool: Tool = {
 	name: SET_TITLE_TOOL_NAME,
 	description: "Set the generated session title.",
@@ -169,7 +176,14 @@ function extractGeneratedTitle(contentBlocks: AssistantMessage["content"]): stri
 			textTitle += content.text;
 		}
 	}
-	return textTitle.trim();
+	// Plain-text fallback (no set_title tool call): only accept it if it actually
+	// looks like a title. A model that ignored the tool and rambled produces a long
+	// blob — reject it so the caller falls back rather than persisting the narrative.
+	const trimmed = textTitle.trim();
+	if (trimmed.length > MAX_TITLE_CHARS || trimmed.split(/\s+/).length > MAX_TITLE_WORDS) {
+		return "";
+	}
+	return trimmed;
 }
 
 /**