@gajae-code/coding-agent 0.11.2 → 0.11.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.11.3] - 2026-07-19
+
+### Changed
+- The `read` tool is now receipt-by-default: bare and unparseable reads return a bounded receipt (≤50 lines / 10 KiB) with a re-read-with-selector footer only when truncated, `:raw` stays pure verbatim up to a max(2 MiB, spill threshold) ceiling, structural summaries cap unit-granularly at 20 KiB while preserving elision and source-recovery footers, and directories are byte/line capped and never spill. Only an explicit full-content selector (`:raw` or an explicit range) with real content is spill-eligible. Subagent previews now enforce a real byte/code-point cap via per-shape render budgets plus a shape-aware artifact-eligibility tag enforced centrally in output-meta.
+
+### Fixed
+- Workflow-state handoff no longer self-locks the active-state cache, so a same-turn skill handoff (e.g. ultragoal → ralplan) completes instead of stalling behind a lock the handoff itself still holds (#2638).
+- SDK host shutdown now retries a failed broker unregister instead of short-circuiting with a stale broker-index entry, while retained startup-cleanup owner-release failures remain isolated from the red extension-error path (#2625).
+- Non-TTY launches now fail fast when stdin is empty and automatically use print mode for positional prompts and `@file` inputs, preventing orphaned interactive TUI processes (#2507).
+
 ## [0.11.2] - 2026-07-19
 
 ### Changed

package/dist/types/cli/launch-disposition.d.ts

@@ -0,0 +1,23 @@
+export type LaunchMode = "text" | "json" | "acp";
+export interface LaunchDisposition {
+    autoPrint: boolean;
+    isInteractive: boolean;
+    /** Set when an interactive launch is impossible (non-TTY stdin, nothing to run). */
+    nonInteractiveError?: string;
+}
+/**
+ * Decides between interactive, auto-print, and fail-fast launches.
+ *
+ * A non-TTY stdin means the TUI can never receive input, so an interactive
+ * launch would execute the initial prompt and then block in the event loop
+ * forever. Prepared command-line input degrades to print mode; without any
+ * input to run we fail fast instead of hanging. Explicit `--print` and
+ * `--mode` launches are left untouched.
+ */
+export declare function resolveLaunchDisposition(args: {
+    stdinIsTTY: boolean | undefined;
+    pipedInput: string | undefined;
+    hasPreparedInput: boolean;
+    print: boolean;
+    mode: LaunchMode | undefined;
+}): LaunchDisposition;

package/dist/types/config/settings-schema.d.ts

@@ -662,15 +662,15 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "tools.readArtifactSpillThreshold": {
         readonly type: "number";
-        readonly default: 0;
+        readonly default: 256;
         readonly ui: {
             readonly tab: "tools";
-            readonly label: "Experimental read-tool artifact spill threshold (KB)";
-            readonly description: "Advanced opt-in only: combined-size cap for `read` output across all requested ranges. Above this the full output is saved as an artifact and a bounded head+tail snippet is kept inline. Live layofflabs/gpt-5.5 medium evidence on 2026-07-07 found no token savings and a lower cache-hit rate at 50 KB, so normal coding sessions should leave this Off unless intentionally measuring large-read behavior.";
+            readonly label: "Read artifact spill threshold (KB)";
+            readonly description: "Explicit large reads above this combined size are saved as an artifact with a bounded head-and-tail snippet inline. Bare reads, directories, and converted-document receipts remain inline.";
             readonly options: readonly [{
                 readonly value: "0";
                 readonly label: "Off";
-                readonly description: "Default; no read-specific spill (backstop only)";
+                readonly description: "No read-specific spill (backstop only)";
             }, {
                 readonly value: "50";
                 readonly label: "50 KB";
@@ -682,7 +682,7 @@ export declare const SETTINGS_SCHEMA: {
             }, {
                 readonly value: "256";
                 readonly label: "256 KB";
-                readonly description: "~64K tokens";
+                readonly description: "Default; ~64K tokens";
             }, {
                 readonly value: "512";
                 readonly label: "512 KB";
@@ -696,11 +696,11 @@ export declare const SETTINGS_SCHEMA: {
     };
     readonly "tools.fileMentionInlineBytes": {
         readonly type: "number";
-        readonly default: 20;
+        readonly default: 10;
         readonly ui: {
             readonly tab: "tools";
             readonly label: "File-mention inline cap (KB)";
-            readonly description: "Inline byte cap for auto-read `@path` file mentions, deliberately below the read-tool cap so an incidental mention injects a smaller snippet than an explicit read. The full file is still available via the read tool.";
+            readonly description: "Inline byte cap for auto-read `@path` file mentions, aligned with the 10 KiB bare-read receipt so incidental mentions stay within the same bounded context budget. The full file is still available via the read tool.";
             readonly options: readonly [{
                 readonly value: "5";
                 readonly label: "5 KB";
@@ -708,15 +708,15 @@ export declare const SETTINGS_SCHEMA: {
             }, {
                 readonly value: "10";
                 readonly label: "10 KB";
-                readonly description: "~2.5K tokens";
+                readonly description: "Default; ~2.5K tokens";
             }, {
                 readonly value: "20";
                 readonly label: "20 KB";
-                readonly description: "Default; ~5K tokens";
+                readonly description: "~5K tokens";
             }, {
                 readonly value: "50";
                 readonly label: "50 KB";
-                readonly description: "~12.5K tokens (matches read cap)";
+                readonly description: "~12.5K tokens (matches bare-read receipt)";
             }];
         };
     };
@@ -2437,6 +2437,81 @@ export declare const SETTINGS_SCHEMA: {
             }];
         };
     };
+    readonly "read.receiptBudgetLines": {
+        readonly type: "number";
+        readonly default: 50;
+        readonly ui: {
+            readonly tab: "editing";
+            readonly label: "Read Receipt Line Budget";
+            readonly description: "Maximum lines included in a bare read receipt before a selector footer is shown";
+            readonly options: readonly [{
+                readonly value: "25";
+                readonly label: "25 lines";
+            }, {
+                readonly value: "50";
+                readonly label: "50 lines";
+                readonly description: "Default";
+            }, {
+                readonly value: "100";
+                readonly label: "100 lines";
+            }, {
+                readonly value: "200";
+                readonly label: "200 lines";
+            }];
+        };
+    };
+    readonly "read.receiptBudgetBytes": {
+        readonly type: "number";
+        readonly default: 10;
+        readonly ui: {
+            readonly tab: "editing";
+            readonly label: "Read Receipt Byte Budget (KB)";
+            readonly description: "Maximum UTF-8 body size for a bare read receipt before a selector footer is shown";
+            readonly options: readonly [{
+                readonly value: "5";
+                readonly label: "5 KB";
+                readonly description: "~1.25K tokens";
+            }, {
+                readonly value: "10";
+                readonly label: "10 KB";
+                readonly description: "Default; ~2.5K tokens";
+            }, {
+                readonly value: "20";
+                readonly label: "20 KB";
+                readonly description: "~5K tokens";
+            }, {
+                readonly value: "50";
+                readonly label: "50 KB";
+                readonly description: "~12.5K tokens";
+            }];
+        };
+    };
+    readonly "read.summaryMaxBytes": {
+        readonly type: "number";
+        readonly default: 20;
+        readonly ui: {
+            readonly tab: "editing";
+            readonly label: "Read Summary Size Budget (KB)";
+            readonly description: "Maximum UTF-8 size for a structural read summary before additional units are elided";
+            readonly options: readonly [{
+                readonly value: "10";
+                readonly label: "10 KB";
+                readonly description: "~2.5K tokens";
+            }, {
+                readonly value: "20";
+                readonly label: "20 KB";
+                readonly description: "Default; ~5K tokens";
+            }, {
+                readonly value: "50";
+                readonly label: "50 KB";
+                readonly description: "~12.5K tokens";
+            }, {
+                readonly value: "100";
+                readonly label: "100 KB";
+                readonly description: "~25K tokens";
+            }];
+        };
+    };
     readonly "read.summarize.enabled": {
         readonly type: "boolean";
         readonly default: true;

package/dist/types/main.d.ts

@@ -118,6 +118,7 @@ export interface RunRootCommandDependencies {
     };
     initTheme?: typeof initTheme;
     readPipedInput?: typeof readPipedInput;
+    stdinIsTTY?: boolean;
     runStartupCredentialAutoImportIfNeeded?: typeof runStartupCredentialAutoImportIfNeeded;
     getChangelogForDisplay?: typeof getChangelogForDisplay;
     createInteractiveMode?: CreateInteractiveMode;

package/dist/types/modes/prompt-action-autocomplete.d.ts

@@ -30,6 +30,10 @@ export declare class PromptActionAutocompleteProvider implements AutocompletePro
         items: AutocompleteItem[];
         prefix: string;
     } | null>;
+    getForceFileSuggestions(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null>;
     applyCompletion(lines: string[], cursorLine: number, cursorCol: number, item: AutocompleteItem, prefix: string): {
         lines: string[];
         cursorLine: number;

package/dist/types/sdk/bus/index.d.ts

@@ -338,6 +338,8 @@ export declare function createNotificationsExtension(api: ExtensionAPI, options?
     /** Suppress auto-delivery for a GJC-spawned child under `sessionScope=primary`. */
     spawnedByGjc?: boolean;
     controller?: NotificationSessionController;
+    /** Whether this host mode can own the root SDK endpoint. Default: true. */
+    sdkHostModeSupported?: boolean;
     onSdkRequest?: (kind: "control" | "query", connectionId: string, frame: Record<string, unknown>) => void;
     runEphemeralTurn?: (promptText: string, signal: AbortSignal) => Promise<{
         replyText: string;

package/dist/types/sdk/session.d.ts

@@ -150,6 +150,8 @@ export interface CreateAgentSessionOptions {
     hasUI?: boolean;
     /** Whether this host mode can own a notification session endpoint. Default: true. */
     notificationHostModeSupported?: boolean;
+    /** Whether this host mode can own the root SDK endpoint. Default: true. */
+    sdkHostModeSupported?: boolean;
     /**
      * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
      * Passing `{}` enables the loop's GenAI-semantic-convention spans. See

package/dist/types/tools/read.d.ts

@@ -27,6 +27,8 @@ export interface ReadToolDetails {
     method?: string;
     notes?: string[];
     meta?: OutputMeta;
+    /** Whether this explicit content read may be spilled by output metadata. */
+    spillEligible?: boolean;
     /** Raw text + start line for user-visible TUI rendering, set when content is text-like.
      * Mirrors the same lines the model receives but without hashline/line-number prefixes,
      * so the TUI can render the file content with its own gutter without re-parsing the formatted text. */

package/dist/types/tools/subagent.d.ts

@@ -98,6 +98,7 @@ export declare class SubagentTool implements AgentTool<typeof subagentSchema, Su
     constructor(session: ToolSession);
     execute(_toolCallId: string, params: SubagentParams, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<SubagentToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<SubagentToolDetails>>;
 }
+export declare function capCodePointsAndBytes(text: string, maxCodePoints: number, maxBytes: number): string;
 /**
  * Canonical, value-based rendered-state signature for the `subagent` await panel.
  *

package/dist/types/utils/file-mentions.d.ts

@@ -1,8 +1,8 @@
 import type { AgentMessage } from "@gajae-code/agent-core";
 /**
- * Default inline cap for auto-read file mentions, deliberately below the
- * read-tool cap (`DEFAULT_MAX_BYTES`, 50KB) so an incidental `@path` mention
- * injects a smaller snippet than an explicit `read`. Overridable per call.
+ * Default inline cap for auto-read file mentions, aligned with the read-tool's
+ * 10 KiB bare-read receipt so an incidental `@path` mention injects a bounded
+ * snippet. Overridable per call.
  */
 export declare const DEFAULT_FILE_MENTION_INLINE_BYTES: number;
 /** Extract all @filepath mentions from text */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.11.2",
+	"version": "0.11.3",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -53,13 +53,13 @@
 		"@agentclientprotocol/sdk": "1.2.1",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.11.2",
-		"@gajae-code/agent-core": "0.11.2",
-		"@gajae-code/ai": "0.11.2",
-		"@gajae-code/bridge-client": "0.11.2",
-		"@gajae-code/natives": "0.11.2",
-		"@gajae-code/tui": "0.11.2",
-		"@gajae-code/utils": "0.11.2",
+		"@gajae-code/stats": "0.11.3",
+		"@gajae-code/agent-core": "0.11.3",
+		"@gajae-code/ai": "0.11.3",
+		"@gajae-code/bridge-client": "0.11.3",
+		"@gajae-code/natives": "0.11.3",
+		"@gajae-code/tui": "0.11.3",
+		"@gajae-code/utils": "0.11.3",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/cli/launch-disposition.ts

@@ -0,0 +1,42 @@
+export type LaunchMode = "text" | "json" | "acp";
+
+export interface LaunchDisposition {
+	autoPrint: boolean;
+	isInteractive: boolean;
+	/** Set when an interactive launch is impossible (non-TTY stdin, nothing to run). */
+	nonInteractiveError?: string;
+}
+
+/**
+ * Decides between interactive, auto-print, and fail-fast launches.
+ *
+ * A non-TTY stdin means the TUI can never receive input, so an interactive
+ * launch would execute the initial prompt and then block in the event loop
+ * forever. Prepared command-line input degrades to print mode; without any
+ * input to run we fail fast instead of hanging. Explicit `--print` and
+ * `--mode` launches are left untouched.
+ */
+export function resolveLaunchDisposition(args: {
+	stdinIsTTY: boolean | undefined;
+	pipedInput: string | undefined;
+	hasPreparedInput: boolean;
+	print: boolean;
+	mode: LaunchMode | undefined;
+}): LaunchDisposition {
+	const explicitNonInteractive = args.print || args.mode !== undefined;
+	const hasPreparedInput = args.pipedInput !== undefined || args.hasPreparedInput;
+	const hasNonTtyStdin = args.stdinIsTTY !== true;
+	const autoPrint = !explicitNonInteractive && hasNonTtyStdin && hasPreparedInput;
+	const isInteractive = !explicitNonInteractive && !autoPrint;
+
+	if (isInteractive && args.stdinIsTTY !== true) {
+		return {
+			autoPrint: false,
+			isInteractive: false,
+			nonInteractiveError:
+				"stdin is not a TTY and no prompt or prepared input was provided; use -p/--print (or pass a prompt or @file) for non-interactive runs.",
+		};
+	}
+
+	return { autoPrint, isInteractive };
+}

package/src/config/settings-schema.ts

@@ -669,17 +669,17 @@ export const SETTINGS_SCHEMA = {
 
 	"tools.readArtifactSpillThreshold": {
 		type: "number",
-		default: 0,
+		default: 256,
 		ui: {
 			tab: "tools",
-			label: "Experimental read-tool artifact spill threshold (KB)",
+			label: "Read artifact spill threshold (KB)",
 			description:
-				"Advanced opt-in only: combined-size cap for `read` output across all requested ranges. Above this the full output is saved as an artifact and a bounded head+tail snippet is kept inline. Live layofflabs/gpt-5.5 medium evidence on 2026-07-07 found no token savings and a lower cache-hit rate at 50 KB, so normal coding sessions should leave this Off unless intentionally measuring large-read behavior.",
+				"Explicit large reads above this combined size are saved as an artifact with a bounded head-and-tail snippet inline. Bare reads, directories, and converted-document receipts remain inline.",
 			options: [
-				{ value: "0", label: "Off", description: "Default; no read-specific spill (backstop only)" },
+				{ value: "0", label: "Off", description: "No read-specific spill (backstop only)" },
 				{ value: "50", label: "50 KB", description: "~12.5K tokens" },
 				{ value: "100", label: "100 KB", description: "~25K tokens" },
-				{ value: "256", label: "256 KB", description: "~64K tokens" },
+				{ value: "256", label: "256 KB", description: "Default; ~64K tokens" },
 				{ value: "512", label: "512 KB", description: "~128K tokens" },
 				{ value: "1000", label: "1 MB", description: "~250K tokens" },
 			],
@@ -688,17 +688,17 @@ export const SETTINGS_SCHEMA = {
 
 	"tools.fileMentionInlineBytes": {
 		type: "number",
-		default: 20,
+		default: 10,
 		ui: {
 			tab: "tools",
 			label: "File-mention inline cap (KB)",
 			description:
-				"Inline byte cap for auto-read `@path` file mentions, deliberately below the read-tool cap so an incidental mention injects a smaller snippet than an explicit read. The full file is still available via the read tool.",
+				"Inline byte cap for auto-read `@path` file mentions, aligned with the 10 KiB bare-read receipt so incidental mentions stay within the same bounded context budget. The full file is still available via the read tool.",
 			options: [
 				{ value: "5", label: "5 KB", description: "~1.25K tokens" },
-				{ value: "10", label: "10 KB", description: "~2.5K tokens" },
-				{ value: "20", label: "20 KB", description: "Default; ~5K tokens" },
-				{ value: "50", label: "50 KB", description: "~12.5K tokens (matches read cap)" },
+				{ value: "10", label: "10 KB", description: "Default; ~2.5K tokens" },
+				{ value: "20", label: "20 KB", description: "~5K tokens" },
+				{ value: "50", label: "50 KB", description: "~12.5K tokens (matches bare-read receipt)" },
 			],
 		},
 	},
@@ -2016,6 +2016,51 @@ export const SETTINGS_SCHEMA = {
 			],
 		},
 	},
+	"read.receiptBudgetLines": {
+		type: "number",
+		default: 50,
+		ui: {
+			tab: "editing",
+			label: "Read Receipt Line Budget",
+			description: "Maximum lines included in a bare read receipt before a selector footer is shown",
+			options: [
+				{ value: "25", label: "25 lines" },
+				{ value: "50", label: "50 lines", description: "Default" },
+				{ value: "100", label: "100 lines" },
+				{ value: "200", label: "200 lines" },
+			],
+		},
+	},
+	"read.receiptBudgetBytes": {
+		type: "number",
+		default: 10,
+		ui: {
+			tab: "editing",
+			label: "Read Receipt Byte Budget (KB)",
+			description: "Maximum UTF-8 body size for a bare read receipt before a selector footer is shown",
+			options: [
+				{ value: "5", label: "5 KB", description: "~1.25K tokens" },
+				{ value: "10", label: "10 KB", description: "Default; ~2.5K tokens" },
+				{ value: "20", label: "20 KB", description: "~5K tokens" },
+				{ value: "50", label: "50 KB", description: "~12.5K tokens" },
+			],
+		},
+	},
+	"read.summaryMaxBytes": {
+		type: "number",
+		default: 20,
+		ui: {
+			tab: "editing",
+			label: "Read Summary Size Budget (KB)",
+			description: "Maximum UTF-8 size for a structural read summary before additional units are elided",
+			options: [
+				{ value: "10", label: "10 KB", description: "~2.5K tokens" },
+				{ value: "20", label: "20 KB", description: "Default; ~5K tokens" },
+				{ value: "50", label: "50 KB", description: "~12.5K tokens" },
+				{ value: "100", label: "100 KB", description: "~25K tokens" },
+			],
+		},
+	},
 
 	"read.summarize.enabled": {
 		type: "boolean",

package/src/gjc-runtime/state-runtime.ts

@@ -1950,9 +1950,16 @@ async function handleHandoff(
 	positionalSkill: string | undefined,
 ): Promise<StateCommandResult> {
 	const selectors = await resolveSelectors(args, cwd, positionalSkill, "handoff");
-	return withWorkflowStateLock(path.relative(cwd, activeStateFile(cwd, selectors.gjcSessionId)), async () =>
-		handleHandoffUnlocked(args, cwd, positionalSkill),
-	);
+	// Serialize concurrent handoffs on a dedicated sentinel lock, NOT on the
+	// derived `skill-active-state.json` cache. The inner transaction
+	// (applyHandoffToActiveState / syncSkillActiveState -> rebuildActiveSnapshot)
+	// re-locks that cache file, and `withFileLock` is not reentrant: holding the
+	// active-state lock here made the inner rebuild self-contend and fail after
+	// all retries whenever `cwd === process.cwd()` (the real CLI case). Pass
+	// `{ cwd }` so the sentinel resolves against the handoff cwd rather than
+	// `process.cwd()`.
+	const handoffLock = path.join(sessionStateDir(cwd, selectors.gjcSessionId), "handoff");
+	return withWorkflowStateLock(handoffLock, async () => handleHandoffUnlocked(args, cwd, positionalSkill), { cwd });
 }
 
 async function handleContract(

package/src/main.ts

@@ -23,6 +23,7 @@ import chalk from "chalk";
 import type { Args } from "./cli/args";
 import { processFileArguments } from "./cli/file-processor";
 import { buildInitialMessage } from "./cli/initial-message";
+import { resolveLaunchDisposition } from "./cli/launch-disposition";
 import { runListModelsCommand } from "./cli/list-models";
 import { selectSession } from "./cli/session-picker";
 import { findConfigFile } from "./config";
@@ -282,7 +283,7 @@ export function resolveAcpStartupOptions(
 }
 
 async function readPipedInput(): Promise<string | undefined> {
-	if (process.stdin.isTTY !== false) return undefined;
+	if (process.stdin.isTTY === true) return undefined;
 	try {
 		const text = await Bun.stdin.text();
 		if (text.trim().length === 0) return undefined;
@@ -292,6 +293,30 @@ async function readPipedInput(): Promise<string | undefined> {
 	}
 }
 
+async function readPipedInputIfReady(): Promise<string | undefined> {
+	if (process.stdin.isTTY === true) return undefined;
+
+	const ready = Promise.withResolvers<void>();
+	const onReadable = () => ready.resolve();
+	const onEnd = () => ready.resolve();
+	const onError = () => ready.resolve();
+	process.stdin.once("readable", onReadable);
+	process.stdin.once("end", onEnd);
+	process.stdin.once("error", onError);
+	await Promise.race([ready.promise, new Promise<void>(resolve => setImmediate(resolve))]);
+	process.stdin.removeListener("readable", onReadable);
+	process.stdin.removeListener("end", onEnd);
+	process.stdin.removeListener("error", onError);
+
+	const chunks: Buffer[] = [];
+	for (let chunk = process.stdin.read(); chunk !== null; chunk = process.stdin.read()) {
+		chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	}
+	if (chunks.length === 0) return undefined;
+	const text = Buffer.concat(chunks).toString("utf8");
+	return text.trim() ? text : undefined;
+}
+
 export interface InteractiveModeNotify {
 	kind: "warn" | "error" | "info";
 	message: string;
@@ -1014,6 +1039,7 @@ export interface RunRootCommandDependencies {
 	startupUpdate?: { check: () => Promise<string | undefined> };
 	initTheme?: typeof initTheme;
 	readPipedInput?: typeof readPipedInput;
+	stdinIsTTY?: boolean;
 	runStartupCredentialAutoImportIfNeeded?: typeof runStartupCredentialAutoImportIfNeeded;
 	getChangelogForDisplay?: typeof getChangelogForDisplay;
 	createInteractiveMode?: CreateInteractiveMode;
@@ -1164,8 +1190,16 @@ export async function runRootCommand(
 	if (parsedArgs.noTitle || parsedArgs.mode === "acp") {
 		Bun.env.PI_NO_TITLE = "1";
 	}
+	const hasPreparedInput = parsedArgs.messages.length > 0 || parsedArgs.fileArgs.length > 0;
 	const { pipedInput, fileText, fileImages } = await logger.time("prepareInitialMessage", async () => {
-		const pipedInput = await (deps.readPipedInput ?? readPipedInput)();
+		const pipedInput =
+			parsedArgs.mode === "acp"
+				? undefined
+				: deps.readPipedInput
+					? await deps.readPipedInput()
+					: hasPreparedInput
+						? await readPipedInputIfReady()
+						: await readPipedInput();
 		if (parsedArgs.fileArgs.length === 0) {
 			return { pipedInput, fileText: undefined, fileImages: undefined };
 		}
@@ -1180,14 +1214,25 @@ export async function runRootCommand(
 		fileImages,
 		stdinContent: pipedInput,
 	});
-	const autoPrint = pipedInput !== undefined && !parsedArgs.print && parsedArgs.mode === undefined;
+	const disposition = resolveLaunchDisposition({
+		stdinIsTTY: deps.stdinIsTTY ?? process.stdin.isTTY,
+		pipedInput,
+		hasPreparedInput,
+		print: Boolean(parsedArgs.print),
+		mode: parsedArgs.mode,
+	});
+	if (disposition.nonInteractiveError) {
+		process.stderr.write(`${chalk.red(disposition.nonInteractiveError)}\n`);
+		process.exit(1);
+	}
+	const autoPrint = disposition.autoPrint;
 	const startupUpdateRoute = classifyStartupUpdateRoute(parsedArgs, autoPrint);
 	const startupUpdate = new StartupUpdateOrchestrator(
 		startupUpdateRoute,
 		() => settingsInstance.get("startup.checkUpdate"),
 		deps.startupUpdate?.check ?? (() => checkForNewVersion(VERSION)),
 	);
-	const isInteractive = startupUpdateRoute === "interactive";
+	const isInteractive = disposition.isInteractive;
 	const mode = parsedArgs.mode || "text";
 
 	// Initialize discovery system with settings for provider persistence
@@ -1319,6 +1364,7 @@ export async function runRootCommand(
 	sessionOptions.modelRegistry = modelRegistry;
 	sessionOptions.hasUI = isInteractive;
 	sessionOptions.notificationHostModeSupported = isInteractive;
+	sessionOptions.sdkHostModeSupported = isInteractive;
 	sessionOptions.settings = settingsInstance;
 	const hasRootStartupProfile = Boolean(settingsInstance.get("modelProfile.default") || parsedArgs.mpreset);
 
@@ -1351,6 +1397,30 @@ export async function runRootCommand(
 		applyCliRuntimeApiKeyOverride(authStorage, parsedArgs.apiKey, sessionOptions.model);
 	}
 
+	if (
+		!deps.suppressProcessExit &&
+		deps.createAgentSession === undefined &&
+		parsedArgs.noSession === true &&
+		!parsedArgs.continue &&
+		parsedArgs.resume === undefined &&
+		parsedArgs.fork === undefined &&
+		!isInteractive &&
+		mode !== "acp" &&
+		!hasRootStartupProfile &&
+		!sessionOptions.model &&
+		!sessionOptions.modelPattern &&
+		modelRegistry.getAvailable().length === 0
+	) {
+		process.stderr.write(`${chalk.red(`No models available. ${formatModelOnboardingGuidance()}`)}\n`);
+		process.stderr.write(
+			`${chalk.yellow(`\nAdvanced manual config remains available at ${ModelsConfigFile.path()}`)}\n`,
+		);
+		process.exitCode = 1;
+		authStorage.close();
+		stopThemeWatcher();
+		await postmortem.cleanup();
+		return;
+	}
 	const createAgentSessionImpl = deps.createAgentSession ?? createAgentSession;
 	const createSession: CreateSessionForMain = async (options, context): Promise<CreateAgentSessionResult> => {
 		const result = await logger.time("createAgentSession", createAgentSessionImpl, options);
@@ -1365,10 +1435,16 @@ export async function runRootCommand(
 	};
 
 	if (mode === "acp") {
-		await (deps.runAcpMode ?? (await import("./modes/acp")).runAcpMode)({
-			agentDir: settingsInstance.getAgentDir(),
-			...(acpStartupOptions ? { startupOptions: acpStartupOptions } : {}),
-		});
+		try {
+			await (deps.runAcpMode ?? (await import("./modes/acp")).runAcpMode)({
+				agentDir: settingsInstance.getAgentDir(),
+				...(acpStartupOptions ? { startupOptions: acpStartupOptions } : {}),
+			});
+		} finally {
+			authStorage.close();
+			stopThemeWatcher();
+			if (!deps.suppressProcessExit) await postmortem.cleanup();
+		}
 	} else {
 		const { session, setToolUIContext, modelFallbackMessage, lspServers, mcpManager, eventBus } = await createSession(
 			sessionOptions,
@@ -1503,20 +1579,21 @@ export async function runRootCommand(
 			}
 		} else {
 			const runPrint = deps.runPrintMode ?? (await import("./modes/print-mode")).runPrintMode;
-			await runPrint(session, {
-				mode,
-				messages: parsedArgs.messages,
-				initialMessage,
-				initialImages,
-				suppressProcessExit: deps.suppressProcessExit,
-			});
-			if ($env.PI_TIMING) {
-				logger.printTimings();
-			}
-			stopThemeWatcher();
-			if (!deps.suppressProcessExit) {
-				const exitCode = typeof process.exitCode === "number" ? process.exitCode : 0;
-				await postmortem.quit(exitCode);
+			try {
+				await runPrint(session, {
+					mode,
+					messages: parsedArgs.messages,
+					initialMessage,
+					initialImages,
+					suppressProcessExit: deps.suppressProcessExit,
+				});
+				if ($env.PI_TIMING) {
+					logger.printTimings();
+				}
+			} finally {
+				stopThemeWatcher();
+				authStorage.close();
+				if (!deps.suppressProcessExit) await postmortem.cleanup();
 			}
 		}
 	}

package/src/modes/prompt-action-autocomplete.ts

@@ -248,6 +248,13 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 
 		return this.#baseProvider.getSuggestions(lines, cursorLine, cursorCol);
 	}
+	getForceFileSuggestions(
+		lines: string[],
+		cursorLine: number,
+		cursorCol: number,
+	): Promise<{ items: AutocompleteItem[]; prefix: string } | null> {
+		return this.#baseProvider.getForceFileSuggestions(lines, cursorLine, cursorCol);
+	}
 
 	applyCompletion(
 		lines: string[],

package/src/sdk/bus/index.ts

@@ -2741,6 +2741,8 @@ export function createNotificationsExtension(
 		/** Suppress auto-delivery for a GJC-spawned child under `sessionScope=primary`. */
 		spawnedByGjc?: boolean;
 		controller?: NotificationSessionController;
+		/** Whether this host mode can own the root SDK endpoint. Default: true. */
+		sdkHostModeSupported?: boolean;
 
 		onSdkRequest?: (kind: "control" | "query", connectionId: string, frame: Record<string, unknown>) => void;
 		runEphemeralTurn?: (promptText: string, signal: AbortSignal) => Promise<{ replyText: string }>;
@@ -2956,7 +2958,8 @@ export function createNotificationsExtension(
 		const lifecycleRequestId = safeLifecycleRequestId(process.env.GJC_LIFECYCLE_REQUEST_ID);
 		const { settings, cfg, settingsAvailable } = resolveSettings(options.settings);
 		const notificationsEnabledForSession = controller.query(ctx).effectiveEnabled;
-		const sdkEnabledForSession = shouldHostSdk(settings, isNotificationEligibleContext(ctx));
+		const sdkEnabledForSession =
+			(options.sdkHostModeSupported ?? true) && shouldHostSdk(settings, isNotificationEligibleContext(ctx));
 		const lifecycleRequired = lifecycleStartupCapability !== undefined;
 		const failLifecycleStartup = (
 			reason: "disabled" | "ineligible" | "failed",

package/src/sdk/host/host.ts

@@ -102,6 +102,7 @@ export class SessionSdkHost {
 	readonly reverse: ReverseLeaseRuntime;
 	readonly #options: SessionSdkHostOptions;
 	#started = false;
+	#stopPromise?: Promise<"stopped">;
 	#unsubscribe?: () => void;
 	#registration?: { writer: BrokerIndexWriter; generation: number };
 
@@ -154,16 +155,27 @@ export class SessionSdkHost {
 	}
 
 	async stop(): Promise<"stopped" | "already"> {
+		if (this.#stopPromise) return this.#stopPromise;
 		if (!this.#started) return "already";
+		const stopPromise = this.#stopStartedHost();
+		this.#stopPromise = stopPromise;
+		try {
+			return await stopPromise;
+		} finally {
+			if (this.#stopPromise === stopPromise) this.#stopPromise = undefined;
+		}
+	}
+
+	async #stopStartedHost(): Promise<"stopped"> {
 		this.#unsubscribe?.();
 		this.#unsubscribe = undefined;
-		this.#started = false;
 		if (this.#registration?.writer.unregister)
 			await this.#registration.writer.unregister({
 				sessionId: this.#options.sessionId,
 				stateRoot: this.#options.stateRoot,
 				endpointGeneration: this.events.generation,
 			});
+		this.#started = false;
 		return "stopped";
 	}
 

package/src/sdk/session.ts

@@ -390,6 +390,8 @@ export interface CreateAgentSessionOptions {
 	hasUI?: boolean;
 	/** Whether this host mode can own a notification session endpoint. Default: true. */
 	notificationHostModeSupported?: boolean;
+	/** Whether this host mode can own the root SDK endpoint. Default: true. */
+	sdkHostModeSupported?: boolean;
 
 	/**
 	 * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
@@ -1763,7 +1765,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				currentAgentType: options.currentAgentType,
 				spawnedByGjc,
 			}) ||
-			shouldHostSdk(notificationCfg, isTopLevelSdkSession)
+			(shouldHostSdk(notificationCfg, isTopLevelSdkSession) && (options.sdkHostModeSupported ?? true))
 		) {
 			inlineExtensions.push(async api => {
 				try {
@@ -1774,6 +1776,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						settings,
 						controller: notificationSessionController,
 						spawnedByGjc,
+						sdkHostModeSupported: options.sdkHostModeSupported,
 						runEphemeralTurn: async (promptText, signal) => {
 							if (!session) throw new Error("Ephemeral turns are unavailable.");
 							const { replyText } = await session.runEphemeralTurn({ promptText, signal });

package/src/tools/output-meta.ts

@@ -605,6 +605,10 @@ async function spillLargeResultToArtifact(
 	toolName: string,
 	context: AgentToolContext | undefined,
 ): Promise<AgentToolResult> {
+	if (toolName === "read" && (result.details as { spillEligible?: boolean } | undefined)?.spillEligible !== true) {
+		return result;
+	}
+
 	const artifactCapability = artifactCapabilityForContext(context);
 	if (!artifactCapability) return result;
 	const { threshold, readThreshold, tailBytes, tailLines, headBytes } = getSpillConfig(context?.settings);
@@ -709,8 +713,8 @@ async function spillLargeResultToArtifact(
 /**
  * Absolute inline-size backstop enforced after {@link spillLargeResultToArtifact}.
  *
- * The threshold-based spill above has escape hatches: it early-returns for the
- * `read` tool and for results that already carry an `artifactId` (a tool may set
+ * The threshold-based spill above has escape hatches: it skips ineligible `read`
+ * results and results that already carry an `artifactId` (a tool may set
  * partial truncation meta yet still emit oversized inline text). This backstop
  * closes those gaps: when `tools.maxInlineResultBytes` is configured (> 0), any
  * final result whose inline text exceeds the cap is force-saved to an artifact

package/src/tools/read.ts

@@ -95,6 +95,8 @@ const CONVERTIBLE_EXTENSIONS = new Set([".pdf", ".doc", ".docx", ".ppt", ".pptx"
 
 const MAX_SUMMARY_BYTES = 2 * 1024 * 1024;
 const MAX_SUMMARY_LINES = 20_000;
+const RAW_COLLECTOR_MAX_BYTES = MAX_SUMMARY_BYTES;
+
 /**
  * Per-line column cap for file reads. Lines wider than the value of
  * `tools.outputMaxColumns` are ellipsis-truncated at display time; the file
@@ -193,6 +195,14 @@ function formatSummaryElisionFooter(readPath: string, elidedSpans: number, elide
 	const linePart = elidedLines > 0 ? `${elidedLines} ${lineWord} across ` : "";
 	return `[${linePart}${elidedSpans} elided ${spanWord}; read ${readPath}:raw or a line range like ${readPath}:1-9999 for verbatim content]`;
 }
+
+function formatReceiptFooter(readPath: string, shownLines: number, totalLines: number, shownBytes: number): string {
+	return `[Showing first ${shownLines} of ${totalLines} lines (~${Math.ceil(shownBytes / 1024)} KiB); re-read ${readPath}:1-${totalLines} or ${readPath}:raw for the full file]`;
+}
+
+function formatSummaryCapFooter(readPath: string, maxBytes: number, totalLines: number): string {
+	return `[Summary truncated at ${Math.ceil(maxBytes / 1024)} KiB; re-read ${readPath}:raw or ${readPath}:1-${totalLines} for the full source]`;
+}
 const READ_CHUNK_SIZE = 8 * 1024;
 
 /**
@@ -532,6 +542,9 @@ export interface ReadToolDetails {
 	method?: string;
 	notes?: string[];
 	meta?: OutputMeta;
+	/** Whether this explicit content read may be spilled by output metadata. */
+	spillEligible?: boolean;
+
 	/** Raw text + start line for user-visible TUI rendering, set when content is text-like.
 	 * Mirrors the same lines the model receives but without hashline/line-number prefixes,
 	 * so the TUI can render the file content with its own gutter without re-parsing the formatted text. */
@@ -816,10 +829,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		options: {
 			details?: ReadToolDetails;
 			sourcePath?: string;
+			spillEligible?: boolean;
+			receiptPath?: string;
 			sourceUrl?: string;
 			sourceInternal?: string;
 			entityLabel: string;
 			ignoreResultLimits?: boolean;
+			resultByteCeiling?: number;
 			raw?: boolean;
 			immutable?: boolean;
 			wrapUntrusted?: boolean;
@@ -871,9 +887,30 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		}
 
 		const endLine = endLineExpanded;
-		const selectedContent = allLines.slice(startLine, endLine).join("\n");
+		let selectedContent = allLines.slice(startLine, endLine).join("\n");
+
+		if (options.receiptPath) {
+			const budgetLines = this.session.settings.get("read.receiptBudgetLines");
+			const budgetBytes = this.session.settings.get("read.receiptBudgetBytes") * 1024;
+			const receiptLines: string[] = [];
+			let bytes = 0;
+			for (const line of allLines) {
+				const lineBytes = Buffer.byteLength(line, "utf-8") + (receiptLines.length > 0 ? 1 : 0);
+				if (receiptLines.length >= budgetLines || bytes + lineBytes > budgetBytes) break;
+				receiptLines.push(line);
+				bytes += lineBytes;
+			}
+			selectedContent = receiptLines.join("\n");
+		}
 		const userLimitedLines = limit !== undefined ? endLine - startLine : undefined;
-		const truncation = ignoreResultLimits ? noTruncResult(selectedContent) : truncateHead(selectedContent);
+		const truncation = ignoreResultLimits
+			? noTruncResult(selectedContent)
+			: truncateHead(
+					selectedContent,
+					options.resultByteCeiling === undefined
+						? undefined
+						: { maxBytes: options.resultByteCeiling, maxLines: Number.MAX_SAFE_INTEGER },
+				);
 
 		const shouldAddHashLines = displayMode.hashLines;
 		const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
@@ -927,7 +964,11 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		} else {
 			outputText = formatText(truncation.content, startLineDisplay);
 		}
+		if (options.receiptPath && (truncation.truncated || countTextLines(selectedContent) < totalLines)) {
+			outputText += `\n\n${formatReceiptFooter(options.receiptPath, countTextLines(selectedContent), totalLines, Buffer.byteLength(selectedContent, "utf-8"))}`;
+		}
 
+		details.spillEligible = options.spillEligible === true && selectedContent.length > 0;
 		resultBuilder.text(options.wrapUntrusted ? wrapUntrustedContent(outputText) : outputText);
 		if (truncationInfo) {
 			resultBuilder.truncation(truncationInfo.result, truncationInfo.options);
@@ -987,6 +1028,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		}
 		const finalText =
 			notices.length > 0 ? (outputText ? `${outputText}\n${notices.join("\n")}` : notices.join("\n")) : outputText;
+		details.spillEligible = parts.length > 0;
+
 		resultBuilder.text(finalText);
 		return resultBuilder.done();
 	}
@@ -1006,6 +1049,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		signal: AbortSignal | undefined,
 	): Promise<{
 		outputText: string;
+		contentLineCount: number;
 		columnTruncated: number;
 		bridgeResult?: AgentToolResult<ReadToolDetails>;
 	}> {
@@ -1027,7 +1071,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					const firstText = bridgeResult.content.find((c): c is TextContent => c.type === "text");
 					if (firstText) firstText.text = `${notice}\n${firstText.text}`;
 				}
-				return { outputText: "", columnTruncated: 0, bridgeResult };
+				return { outputText: "", contentLineCount: 0, columnTruncated: 0, bridgeResult };
 			} catch (error) {
 				logger.warn("ACP fs readTextFile failed; falling back to disk", { path: absolutePath, error });
 			}
@@ -1040,6 +1084,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const blocks: string[] = [];
 		const notices: string[] = [];
 		let columnTruncated = 0;
+		let contentLineCount = 0;
 
 		for (const range of ranges) {
 			const rangeStart = range.startLine - 1; // 0-indexed
@@ -1074,6 +1119,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				}
 			}
 
+			contentLineCount += collectedLines.length;
 			if (collectedLines.length > 0) {
 				getFileReadCache(this.session).recordContiguous(absolutePath, range.startLine, collectedLines);
 			}
@@ -1086,7 +1132,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		if (notices.length > 0) {
 			outputText = outputText ? `${outputText}\n${notices.join("\n")}` : notices.join("\n");
 		}
-		return { outputText, columnTruncated };
+		return { outputText, contentLineCount, columnTruncated };
 	}
 
 	async #readArchiveDirectory(
@@ -1369,6 +1415,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		displayText: string;
 		elidedSpans: number;
 		elidedLines: number;
+		capped: boolean;
 	} {
 		const displayMode = resolveFileDisplayMode(this.session);
 		const shouldAddHashLines = displayMode.hashLines;
@@ -1428,17 +1475,19 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 		const modelParts: string[] = [];
 		const displayParts: string[] = [];
+		const capBytes = this.session.settings.get("read.summaryMaxBytes") * 1024;
+		let usedBytes = 0;
 		let elidedSpans = 0;
 		let elidedLines = 0;
+		let capDropped = false;
 		for (const unit of units) {
+			let model: string;
+			let display: string;
+			let implicitElidedLines = 0;
 			if (unit.kind === "elided") {
-				modelParts.push("...");
-				displayParts.push("...");
-				elidedSpans++;
-				elidedLines += unit.endLine - unit.startLine + 1;
-				continue;
-			}
-			if (unit.kind === "merged") {
+				model = display = "...";
+				implicitElidedLines = unit.endLine - unit.startLine + 1;
+			} else if (unit.kind === "merged") {
 				const formatted = formatMergedBraceLine(
 					unit.startLine,
 					unit.endLine,
@@ -1447,18 +1496,39 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					shouldAddHashLines,
 					shouldAddLineNumbers,
 				);
-				modelParts.push(formatted.model);
-				displayParts.push(formatted.display);
+				model = formatted.model;
+				display = formatted.display;
+				implicitElidedLines = Math.max(0, unit.endLine - unit.startLine - 1);
+			} else {
+				model = formatSingleLine(unit.line, unit.text, shouldAddHashLines, shouldAddLineNumbers);
+				display = unit.text;
+			}
+			const separatorBytes = modelParts.length > 0 ? 1 : 0;
+			if (usedBytes + separatorBytes + Buffer.byteLength(model, "utf-8") > capBytes) {
+				capDropped = true;
 				elidedSpans++;
-				// Merged brace pair encloses (start+1)..(end-1) as elided.
-				elidedLines += Math.max(0, unit.endLine - unit.startLine - 1);
+				elidedLines += unit.kind === "line" ? 1 : unit.endLine - unit.startLine + 1;
 				continue;
 			}
-			modelParts.push(formatSingleLine(unit.line, unit.text, shouldAddHashLines, shouldAddLineNumbers));
-			displayParts.push(unit.text);
+			usedBytes += separatorBytes + Buffer.byteLength(model, "utf-8");
+			modelParts.push(model);
+			displayParts.push(display);
+			if (unit.kind === "elided" || unit.kind === "merged") {
+				elidedSpans++;
+				elidedLines += implicitElidedLines;
+			}
 		}
-
-		return { text: modelParts.join("\n"), displayText: displayParts.join("\n"), elidedSpans, elidedLines };
+		if (capDropped) {
+			modelParts.push("…");
+			displayParts.push("…");
+		}
+		return {
+			text: modelParts.join("\n"),
+			displayText: displayParts.join("\n"),
+			elidedSpans,
+			elidedLines,
+			capped: capDropped,
+		};
 	}
 
 	async execute(
@@ -1649,25 +1719,38 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				details: { resolvedPath: absolutePath },
 				sourcePath: absolutePath,
 				entityLabel: "notebook",
+				spillEligible: parsed.kind !== "none",
+				resultByteCeiling:
+					parsed.kind !== "none"
+						? Math.max(
+								RAW_COLLECTOR_MAX_BYTES,
+								this.session.settings.get("tools.readArtifactSpillThreshold") * 1024,
+							)
+						: undefined,
+				receiptPath: parsed.kind === "none" ? localReadPath : undefined,
 			});
 		} else if (shouldConvertWithMarkit) {
-			// Convert document via markit.
 			const result = await convertFileWithMarkit(absolutePath, signal);
 			if (result.ok) {
-				// Apply truncation to converted content
-				const truncation = truncateHead(result.content);
-				const outputText = truncation.content;
-
-				details = { truncation };
-				sourcePath = absolutePath;
-				truncationInfo = { result: truncation, options: { direction: "head", startLine: 1 } };
-
-				content = [{ type: "text", text: outputText }];
-			} else if (result.error) {
-				content = [{ type: "text", text: `[Cannot read ${ext} file: ${result.error || "conversion failed"}]` }];
-			} else {
-				content = [{ type: "text", text: `[Cannot read ${ext} file: conversion failed]` }];
+				const { offset, limit } = selToOffsetLimit(parsed);
+				return this.#buildInMemoryTextResult(result.content, offset, limit, {
+					details: { resolvedPath: absolutePath },
+					sourcePath: absolutePath,
+					entityLabel: "converted document",
+					raw: isRawSelector(parsed),
+					spillEligible: parsed.kind !== "none",
+					resultByteCeiling:
+						parsed.kind !== "none"
+							? Math.max(
+									RAW_COLLECTOR_MAX_BYTES,
+									this.session.settings.get("tools.readArtifactSpillThreshold") * 1024,
+								)
+							: undefined,
+					receiptPath: parsed.kind === "none" ? localReadPath : undefined,
+				});
 			}
+			content = [{ type: "text", text: `[Cannot read ${ext} file: ${result.error || "conversion failed"}]` }];
+			details = { spillEligible: false };
 		} else {
 			if (
 				parsed.kind === "none" &&
@@ -1682,8 +1765,22 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						renderedSummary.elidedSpans,
 						renderedSummary.elidedLines,
 					);
-					const modelText = footer ? `${renderedSummary.text}\n\n${footer}` : renderedSummary.text;
+					const summaryTotalLines = Math.max(...summary.segments.map(segment => segment.endLine));
+					const modelText = [
+						renderedSummary.text,
+						footer,
+						renderedSummary.capped
+							? formatSummaryCapFooter(
+									localReadPath,
+									this.session.settings.get("read.summaryMaxBytes") * 1024,
+									summaryTotalLines,
+								)
+							: "",
+					]
+						.filter(Boolean)
+						.join("\n\n");
 					details = {
+						spillEligible: false,
 						displayContent: { text: renderedSummary.displayText, startLine: 1 },
 						summary: {
 							lines: countTextLines(renderedSummary.text),
@@ -1710,7 +1807,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					if (multiResult.bridgeResult) return multiResult.bridgeResult;
 					content = [{ type: "text", text: multiResult.outputText }];
 					sourcePath = absolutePath;
-					details = {};
+					details = { spillEligible: multiResult.contentLineCount > 0 };
 					if (multiResult.columnTruncated > 0) {
 						columnTruncated = multiResult.columnTruncated;
 					}
@@ -1750,13 +1847,25 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					const startLine = requestedStart - leadingContext;
 					const startLineDisplay = startLine + 1;
 
+					const isBareReceipt = parsed.kind === "none" && !content;
+					const rawSelector = isRawSelector(parsed);
 					const DEFAULT_LIMIT = this.#defaultLimit;
-					const effectiveLimit = limit ?? DEFAULT_LIMIT;
-					const maxLinesToCollect = Math.min(effectiveLimit + leadingContext + trailingContext, DEFAULT_MAX_LINES);
-					const selectedLineLimit = effectiveLimit + leadingContext + trailingContext;
-					// Scale byte budget with line limit so the configured line count actually fits.
-					// Assume ~512 bytes/line average; never go below the shared default.
-					const maxBytesForRead = Math.max(DEFAULT_MAX_BYTES, maxLinesToCollect * 512);
+					const effectiveLimit = rawSelector ? Number.MAX_SAFE_INTEGER : (limit ?? DEFAULT_LIMIT);
+					const receiptBudgetBytes = this.session.settings.get("read.receiptBudgetBytes") * 1024;
+					const maxLinesToCollect = rawSelector
+						? Number.MAX_SAFE_INTEGER
+						: isBareReceipt
+							? this.session.settings.get("read.receiptBudgetLines")
+							: Math.min(effectiveLimit + leadingContext + trailingContext, DEFAULT_MAX_LINES);
+					const selectedLineLimit = rawSelector ? null : effectiveLimit + leadingContext + trailingContext;
+					const maxBytesForRead = rawSelector
+						? Math.max(
+								RAW_COLLECTOR_MAX_BYTES,
+								this.session.settings.get("tools.readArtifactSpillThreshold") * 1024,
+							)
+						: isBareReceipt
+							? receiptBudgetBytes
+							: Math.max(DEFAULT_MAX_BYTES, maxLinesToCollect * 512);
 
 					const streamResult = await streamLinesFromFile(
 						absolutePath,
@@ -1793,7 +1902,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 					// verbatim bytes for paste-back-into-tool workflows. Total byte/line
 					// counts in `truncation` keep reflecting the source, not the trimmed
 					// view — column truncation surfaces separately via `.limits()`.
-					const rawSelector = isRawSelector(parsed);
+
 					const shouldAddHashLines = !rawSelector && displayMode.hashLines;
 					const maxColumns = resolveOutputMaxColumns(this.session.settings);
 					if (!rawSelector && !shouldAddHashLines && maxColumns > 0) {
@@ -1855,7 +1964,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 								firstLineBytes,
 							)}, exceeds ${formatBytes(maxBytesForRead)} limit. Unable to display a valid UTF-8 snippet.]`;
 						}
-						details = { truncation };
+						details = { truncation, spillEligible: !isBareReceipt && collectedLines.length > 0 };
+
 						sourcePath = absolutePath;
 						truncationInfo = {
 							result: truncation,
@@ -1863,7 +1973,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						};
 					} else if (truncation.truncated) {
 						outputText = formatText(truncation.content, startLineDisplay);
-						details = { truncation };
+						details = { truncation, spillEligible: !isBareReceipt && collectedLines.length > 0 };
+
 						sourcePath = absolutePath;
 						truncationInfo = {
 							result: truncation,
@@ -1875,14 +1986,22 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 						outputText = formatText(truncation.content, startLineDisplay);
 						outputText += `\n\n[${remaining} more lines in file. Use :${nextOffset} to continue]`;
-						details = {};
+						details = { spillEligible: !isBareReceipt && collectedLines.length > 0 };
+
 						sourcePath = absolutePath;
 					} else {
 						// No truncation, no user limit exceeded
 						outputText = formatText(truncation.content, startLineDisplay);
-						details = {};
+						details = { spillEligible: !isBareReceipt && collectedLines.length > 0 };
+
 						sourcePath = absolutePath;
 					}
+					if (isBareReceipt && (truncation.truncated || collectedLines.length < totalFileLines)) {
+						outputText += `\n\n${formatReceiptFooter(localReadPath, collectedLines.length, totalFileLines, collectedBytes)}`;
+					}
+					if (rawSelector && truncation.truncated) {
+						outputText += `\n\n[Raw read capped at ${formatBytes(maxBytesForRead)} of ${formatBytes(fileSize)}; re-read a line range to narrow the view]`;
+					}
 
 					if (capturedDisplayContent) {
 						details.displayContent = capturedDisplayContent;
@@ -2109,23 +2228,23 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		}
 		throwIfAborted(signal);
 
-		const output = tree.totalLines <= 1 ? "(empty directory)" : tree.rendered;
-		const truncation = truncateHead(output, { maxLines: Number.MAX_SAFE_INTEGER });
-		const details: ReadToolDetails = {
-			isDirectory: true,
-			resolvedPath: tree.rootPath,
-		};
-
-		const resultBuilder = toolResult(details).text(truncation.content).sourcePath(tree.rootPath);
-		if (tree.truncated) {
-			resultBuilder.limits({ resultLimit: 1 });
-		}
-		if (truncation.truncated) {
-			resultBuilder.truncation(truncation, { direction: "head" });
-			details.truncation = truncation;
-		}
-
-		return resultBuilder.done();
+		const receiptLines = this.session.settings.get("read.receiptBudgetLines");
+		const receiptBytes = this.session.settings.get("read.receiptBudgetBytes") * 1024;
+		const sourceLines = tree.totalLines <= 1 ? ["(empty directory)"] : tree.rendered.split("\n");
+		const bodyLines: string[] = [];
+		let bodyBytes = 0;
+		for (const line of sourceLines) {
+			const bytes = Buffer.byteLength(line, "utf-8") + (bodyLines.length > 0 ? 1 : 0);
+			if (bodyLines.length >= receiptLines || bodyBytes + bytes > receiptBytes) break;
+			bodyLines.push(line);
+			bodyBytes += bytes;
+		}
+		let output = bodyLines.join("\n");
+		if (bodyLines.length < sourceLines.length || tree.truncated) {
+			output += `\n\n[Listing truncated at ${bodyLines.length} lines / ${Math.ceil(bodyBytes / 1024)} KiB; read a deeper subpath (e.g. ${absolutePath}/<subdir>) to narrow the view]`;
+		}
+		const details: ReadToolDetails = { isDirectory: true, spillEligible: false, resolvedPath: tree.rootPath };
+		return toolResult(details).text(output).sourcePath(tree.rootPath).done();
 	}
 }
 

package/src/tools/subagent.ts

@@ -17,6 +17,10 @@ const MAX_LIST_LIMIT = 50;
 const RECEIPT_PREVIEW_WIDTH = 280;
 const PREVIEW_WIDTH = 2_000;
 const FULL_PREVIEW_WIDTH = 12_000;
+const RECEIPT_PREVIEW_BYTES = 1_024;
+const PREVIEW_BYTES = 8_192;
+const FULL_PREVIEW_BYTES = 49_152;
+
 const STEER_QUEUED_GUIDANCE =
 	"The steer message is queued for the subagent's next steering boundary and has not necessarily taken effect yet.";
 
@@ -783,7 +787,40 @@ function isSubagentJob(job: AsyncJob): boolean {
 }
 
 function sanitizeText(text: string, width: number): string {
-	return truncateToWidth(replaceTabs(text), width, Ellipsis.Unicode);
+	return capCodePointsAndBytes(
+		truncateToWidth(replaceTabs(text), width, Ellipsis.Unicode),
+		width,
+		previewByteCap(width),
+	);
+}
+
+function previewByteCap(width: number): number {
+	return width === FULL_PREVIEW_WIDTH
+		? FULL_PREVIEW_BYTES
+		: width === PREVIEW_WIDTH
+			? PREVIEW_BYTES
+			: RECEIPT_PREVIEW_BYTES;
+}
+
+export function capCodePointsAndBytes(text: string, maxCodePoints: number, maxBytes: number): string {
+	const ellipsis = "…";
+	const collapsed = text.replace(/…{2,}$/u, ellipsis);
+	const codePoints = [...collapsed];
+	if (codePoints.length <= maxCodePoints && Buffer.byteLength(collapsed) <= maxBytes) return collapsed;
+
+	const source = collapsed.endsWith(ellipsis) ? collapsed.slice(0, -ellipsis.length) : collapsed;
+	const ellipsisBytes = Buffer.byteLength(ellipsis);
+	let preview = "";
+	let previewBytes = 0;
+	let previewCodePoints = 0;
+	for (const codePoint of source) {
+		const codePointBytes = Buffer.byteLength(codePoint);
+		if (previewCodePoints + 1 + 1 > maxCodePoints || previewBytes + codePointBytes + ellipsisBytes > maxBytes) break;
+		preview += codePoint;
+		previewBytes += codePointBytes;
+		previewCodePoints++;
+	}
+	return `${preview}${ellipsis}`;
 }
 
 function previewJobOutput(
@@ -799,7 +836,11 @@ function previewJobOutput(
 	const width =
 		verbosity === "full" ? FULL_PREVIEW_WIDTH : verbosity === "preview" ? PREVIEW_WIDTH : RECEIPT_PREVIEW_WIDTH;
 	const normalized = replaceTabs(source.text);
-	const preview = truncateToWidth(normalized, width, Ellipsis.Unicode);
+	const preview = capCodePointsAndBytes(
+		truncateToWidth(normalized, width, Ellipsis.Unicode),
+		width,
+		previewByteCap(width),
+	);
 	return { type: source.type, preview, truncated: preview !== normalized };
 }
 

package/src/utils/file-mentions.ts

@@ -160,11 +160,11 @@ async function resolveMentionPath(
 }
 
 /**
- * Default inline cap for auto-read file mentions, deliberately below the
- * read-tool cap (`DEFAULT_MAX_BYTES`, 50KB) so an incidental `@path` mention
- * injects a smaller snippet than an explicit `read`. Overridable per call.
+ * Default inline cap for auto-read file mentions, aligned with the read-tool's
+ * 10 KiB bare-read receipt so an incidental `@path` mention injects a bounded
+ * snippet. Overridable per call.
  */
-export const DEFAULT_FILE_MENTION_INLINE_BYTES = 20 * 1024;
+export const DEFAULT_FILE_MENTION_INLINE_BYTES = 10 * 1024;
 
 function buildTextOutput(textContent: string, maxInlineBytes?: number): { output: string; lineCount: number } {
 	const cap = maxInlineBytes && maxInlineBytes > 0 ? maxInlineBytes : DEFAULT_FILE_MENTION_INLINE_BYTES;